Catalogue of functions by source file:
Supporting files:
Introduction to C function library for 4gl
USAGE:
function c_open(path, oflag, mode char(*)) returning integer
function c_pipe() returning (rfd, wfd) integer
function c_dup(fd integer) returning (nfd) integer
function c_dup2(fd1, fd2 integer) returning (fd) integer
function c_close(fd integer) returning (stat) integer
function c_read(fd, n integer) returning (nbytes) integer, (str) char(*)
function c_write(fd integer, str char(*), n integer) returning (nbytes) integer
function c_lseek(fd, ofs, whence integer) returning integer
function c_chmod(path, mode char(*)) returning integer
DESCRIPTION:
Most of these functions are adequately described in the standard manual pages. Following are some special points to note.
open() oflags may contain the following characters:
'r' Open for reading
'w' Open for writing
'a' Append - O/S set file pointer to end prior to each write
'c' Create - allow creation of non-existent file
'e' Exclusive - force failure if file exists (must use with 'c')
's' Sync - writes wait for file data and status to be updated
't' Truncate - affects existing regular files only
'y' No CTTY - prevents a terminal device becoming the controlling
terminal for a process without a controller.
'b' Non-blocking I/O - different behaviour to 'd' (so the manual says)
'd' No delay I/O - different behaviour to 'b' (so the manual says)
The mode flag for c_open() and c_chmod() must be a string, but it can be either octal digits, or "rwxrwxrwx", with - in position for any unset bits. If the string is too short, trailing bits are assumed to be - ie unset.
If the length parameter given to c_write() is zero, then the length of the string is calculated - trailing blanks are ignored in the 4GL tradition. If you specify the length then you can get away with blanks, but make sure those blanks are actually in the string.
All functions store errno whenever the system call returns an error. See c_errno() and c_strerror()
WARNINGS:
Maximum length for a filename is 1024 bytes. Maximum read and write strings are 2048 bytes. Extra characters are silently discarded. Beware writing nulls in strings - I have a nasty feeling the remaining characters will not get delivered to the write() system call, due to the nature of 4GL string handling. If that's a problem, we can write a simple lowlevel writebyte() which takes a numeric parameter.
USAGE:
function c_fork() returning (pid) integer
function c_wait() returning (pid, status) integer
function c_waitpid(pid, options integer) returning (pid, status) integer
function c_waitopt(option char(*)) returning integer
function c_waitstat(funct char(*), status integer) returning integer
function c_sqldetach()
function c_argv(arg char(*)) returning integer
function c_argc() returning (argc, max_argv, max_argc) integer
function c_execv(path char(*)) returning integer
function c_execvp(file char(*)) returning integer
DESCRIPTION:
c_fork() flushes all open FILE streams, wac_errno, child does sqldetach()
c_wait() and c_waitopt() wait for a child process, and return the process ID and status of the result.
c_waitopt() returns constants to be used in the c_waitpid() call. Supported options are:
"WCONTINUED"
"WNOHANG"
"WNOWAIT"
"WUNTRACED"
c_waitstat() performs the duties of the named macros, as documented for the waitpid() system call. Supported macros are:
"WIFEXITED"
"WEXITSTATUS"
"WIFSIGNALED"
"WTERMSIG"
"WCOREDUMP"
c_argv() stores the (next) string for a subsequent call of execv() or execvp() A null argument frees all stored strings and resets the array to empty.
TODO: probably should have a different clearing convention, like NO args
c_argc() returns the present number of stored arguments, the maximum allowed length for an argument and the maximum number of arguments allowed.
c_execv() calls the execv() system call using the path given and the previously stored arguments, and c_execvp() calls the execvp() system call which searches for the named file using $PATH. If these functions return then they has failed - see below for return values.
function c_execvp(file char(*)) returning integer
RETURN VALUES:
c_fork() returns -1 on failure and stores errno, returns 0 for the child process and returns the child process id to the parent process.
c_wait() and c_waitpid() return -1 on failure and store errno.
c_waitopt() and c_waitstat() craps out if an unknown option is passed.
c_argv() return values are:
0 after clearing the remembered arguments.
-1 exceeded maximum argument count.
-2 failed to allocate memory for the new argument.
n number of arguments now stored
c_execv() and c_execvp() both return -1 (if they return at all) and errno is stored. The argv array is not cleared - you may want to call again with the same values.
WARNING:
c_fork() correctly detaches the child process from the database, thus the child process may call execv() or execvp() without trouble. If a parent process (or a process whih hasn't forked) wants to call one of the exec functions, then it MUST close the database and then call c_sqldetach(). Heinous results may ensue if this is not done. I'm not sure the consequences of calling c_sqldetach() when already detached (ie in a child for example).
If a child process opens a database, then it is reattached and will need to call c_sqldetach() if it wants to call an exec function.
USAGE:
function c_crypt(char(100), char(15)) returning char(15)
function c_setpwent()
function c_endpwent()
function c_getpwent()
returning (name, passwd) char(*),
(uid, gid) integer,
(age, comment, gecos, dir, shell) char(*)
function c_getpwuid(int)
returning (name, passwd) char(*),
(uid, gid) integer,
(age, comment, gecos, dir, shell) char(*)
function c_getpwnam(char (8))
returning (name, passwd) char(*),
(uid, gid) integer,
(age, comment, gecos, dir, shell) char(*)
DESCRIPTION:
c_crypt() returns the string result of calling crypt(key, salt). Note that the first two characters of an encrypted password stored in /etc/passwd are the salt.
c_setpwent(), c_getpwent() and c_endpwent() perform lookups into /etc/passwd or NIS (formerly YP) as appropriate for the machine.
c_setpwent() opens the password file stream, and c_endpwent() closes it.
c_getpwent() when called sequentially returns each row of the password stream, returning all-nulls when the stream is finished.
c_getpwuid() and c_getpwnam() return a password record keyed by uid and name respectively.
USAGE:
c_alarm(name char(10))
set an alarm, according to the named duration
c_alarmed() returning integer
get and reset the alarmed indicator
DESCRIPTION:
Alarm times are specified by name, to allow changes in the timing without having to rewrite and recompile programs. The names are looked up in the environment as ${FGL_TO_<name>}. If this value exists as an environment variable, it is used as the duration of the timing. Note that the $name part is expected to be lowercase.
Any value not explicitly exported uses the value $FGL_TO_TIMEOUT. The default for $FGL_TO_TIMEOUT is 900 (ie 15 minutes). A non-positive or null timeout means the named timeout is disabled, and any existing alarm is cleared. There may be up to 20 timeout names. Only one alarm can be set at a time; old alarms are implicitly cancelled when a new alarm is set. An existing alarm can be cancelled by passing a null name.
The libraries and generator (will) use these standard timeouts:
FGL_TO_menu timeout for exiting program from main ring menu
FGL_TO_input timeout for data entry in header/detail screen
FGL_TO_cancel timeout for the popup cancel window
FGL_TO_zoom timeout for closing down zoom screens
FGL_TO_view timeout for other popup view screens
FGL_TO_edit timeout for other popup edit screens
Feel free to invent 8 of your own, but I would like to reserve 6 more for the libraries.
Internally, the timeouts are set by calling the alarm() system call. When the alarm goes off, the operating system sends the SIGALRM signal. When this signal is caught, the alarm is registered in a static C variable and the process then sends SIGINT to itself. Informix registers this interrupt by interrupting whatever it feels like, and setting int_flag. Finally, all the alarm interrupt handlers return. The 4GL program then continues as if a genuine interrupt has been sent by the user. The 4GL interrupt handling code can detect the alarm by calling c_alarmed() which, if it returns true, implies that the interrupt is actually an alarm signal.
USAGE:
function c_getprotobyname(name char(*))
returning (name) char(*), (nalias, proto) integer
function c_getprotobynumber(proto integer)
returning (name) char(*), (nalias, proto) integer
function c_proto_alias(nalias integer)
returning (alias) char(*)
DESCRIPTION:
Protocols referred to here imply lowlevel Internet protocols eg IP TCP UDP.
c_getprotobyname() performs a lookup by name, and c_getprotobynumber() performs a lookup by number.
RETURN VALUES:
Both functions return the official name, number of name aliases and the protocol number. Nulls are returned if the protocol cannot be found. Name aliases are stored in a static array which is overwritten by each call, and may be fetched using the c_proto_alias() function.
USAGE:
function c_getservbyname(name, protocol char(*))
returning (name) char(*), (nalias, port) integer, (protocol) char(*)
function c_getservbyport(port integer, protocol char(*))
returning (name) char(*), (nalias, port) integer, (protocol) char(*)
function c_serv_alias(nalias integer)
returning (alias) char(*)
DESCRIPTION:
Services here imply members of the /etc/services file or members of the services table of NIS (formerly YP) as appropriate for the machine.
c_getservbyname() performs a lookup by name, and c_getservbyport() performs a lookup by number. The protocol argument must be passed as a lowercase string (eg tcp or udp) as found in the /etc/services file. If a null protocol is passed, the first service found is returned.
RETURN VALUES:
Both functions return the official service name, the number of name aliases, the port number of the service and the name of the protocol. Nulls are returned if the service cannot be found. Name aliases are stored in a static array which is overwritten by each call, and may be fetched using the c_serv_alias() function.
USAGE:
function c_gethostname() returning (hostname) char(*)
DESCRIPTION:
Returns the primary name of the host. Null is returned and errno is stored if the hostname cannot be found. See the manual entry for the gethostname() system call for details.
USAGE:
function c_gethostbyname(name char(*))
returning (name) char(*), (nalias, naddr) integer
function c_gethostbyaddr(ipaddr char(*))
returning (name) char(*), (nalias, naddr) integer
function c_host_alias(nalias integer) returning (alias) char(*)
function c_host_addr(naddr integer) returning (addr) char(*)
DESCRIPTION:
c_gethostbyname() performs a name lookup, and c_gethostbyaddr() performs a lookup by IP address. See resolv.conf, DNS nis (formerly YP) and /etc/hosts for resolution details; they are what you would expect if you expect the right thing. The address should be specified as text eg 192.168.105.104. Only the internet address format is understood.
RETURN VALUES:
Both functions return the official name of the host, the number of name aliases and the number of addresses for the machine. The list of aliases and the list of addresses are stored in static arrays which are overwritten by each call.
The aliases can be fetched using c_host_alias(), and the addresses can be fetched using c_host_addr(). The address is returned in dotted format.
function c_getuid() returning integer
function c_geteuid() returning integer
function c_getgid() returning integer
function c_getegid() returning integer
function c_getpid() returning integer
function c_getppid() returning integer
These functions return the values of the corresponding system call. These functions cannot fail, so there is no error return value.
function c_ttyname() returning char(*)
This function examines the first three I/O streams in an attempt to get the name of the controlling terminal. If the controlling terminal cannot be found, the function returns a null string, and errno is stored.
function c_mkdir(path [, mode] char(*)) returning integer
Creates a directory by calling the mkdir() system call. The mode can either be an octal number (passed as a string!) or passed as a permissions string rwxrwxrwx. Unset bits should be passed as a - character. Missing character positions on the end of the string are assumed to be - The default mode is 0777.
Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and errno is stored. See c_errno() and c_strerror()
function c_chdir(path char(*)) returning integer
change the current working directory of the process to path. Upon success, returns 0. Upon failure, returns -1 and stores errno. See c_errno()
function c_daemon() returning integer
Changes session and process group id's closes highlevel FILE streams stdin, stderr, and stdout closes lowlevel file streams 0, 1, 2
return value is the new process group id if successful; returns -1 and stores errno on failure. See c_errno() and c_strerror() functions
USAGE:
function c_is4js() returning integer
DESCRIPTION:
This simple function returns true if running under a FourJays runner, and false if running under RDS or 4GL/C
Probably should be supersceded by a function which returns a string so that multiple 4GL products can be supported.