[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

decc$feature_get_value

Returns a feature value specified by the index and mode arguments.

Format

#include <unixlib.h>
int decc$feature_get_value (int index, int mode);

Arguments

index
An integer value from 0 to the highest allocated feature.
mode
An integer indicating which feature value to return. The values for mode are:
__FEATURE_MODE_DEFVAL Default value
__FEATURE_MODE_CURVAL Current value
__FEATURE_MODE_MINVAL Minimum value
__FEATURE_MODE_MAXVAL Maximum value
__FEATURE_MODE_INIT_STATE Initialization state

Description

The decc$feature_get_value function retrieves a value for the feature specified by index. The mode determines which value is returned.
The default value is what is used if not set by a logical name or overidden by a call to decc$feature_set_value .
If mode = 4, then the initialization state is returned. Values for the initialization state are:
0 not initialized
1 set by logical name
2 forced by decc$feature_set_value
- 1---initialized to default value

On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_get , decc$feature_get_index , decc$feature_get_name , decc$feature_set , decc$feature_set_value , decc$feature_show , and decc$feature_show_all .

Return Values

n An integer corresponding to the specified index and mode arguments.

- 1 Indicates an error; errno is set.

decc$feature_set

Calls decc$feature_set_value with a character-string feature name, rather than an index.

Format

#include <unixlib.h>
int decc$feature_set (const char *name, int mode, int value);

Argument

name
Pointer to a character string passed as a name in the list of supported features.
mode
An integer indicating which feature value to return. The values for mode are:
__FEATURE_MODE_DEFVAL Default value
__FEATURE_MODE_CURVAL Current value
__FEATURE_MODE_MINVAL Minimum value
__FEATURE_MODE_MAXVAL Maximum value
__FEATURE_MODE_INIT_STATE Initialization state

value
The feature value to be set.

Description

The decc$feature_set function allows you to call the decc$feature_set_value function with a character-string feature name, rather than an index into an internal C RTL table.
If successful, the function returns the previous value.
On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_set_value , decc$feature_get , decc$feature_get_index , decc$feature_get_name , decc$feature_get_value . decc$feature_show , and decc$feature_show_all .

Return Values

n The previous feature value.

- 1 Indicates an error; errno is set.

decc$feature_set_value

Sets the default value or the current value for the feature specified by index.

Format

#include <unixlib.h>
int decc$feature_set_value (int index, int mode, int value);

Arguments

index
An integer value from 0 to the highest allocated feature.
mode
An integer indicating whether to set the default or current feature value. The values for mode are:
0 default value
1 current value

value
The feature value to be set.

Description

The decc$feature_set_value function sets the default value or the current value (as determined by the mode argument) for the feature specified by index.
If this function is successful, it returns the previous value.
On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_get , decc$feature_get_index , decc$feature_get_name , decc$feature_get_value , decc$feature_set , decc$feature_show , and decc$feature_show_all .

Return Values

n The previous feature value.

- 1 Indicates an error; errno is set.

decc$feature_show

Displays all feature values for the specified feature name.

Format

#include <unixlib.h>
int decc$feature_show (const char *name);

Argument

name
Pointer to a character string passed as a name in the list of supported features.

Description

The decc$feature_show function displays to stdout all values for the specified feature name. For example:
--------- C RTL Feature Name --------- Cur Def Min Max Ini DECC$V62_RECORD_GENERATION 0 0 0 1 -1
On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_get , decc$feature_get_index , decc$feature_get_name , decc$feature_get_value , decc$feature_set , decc$feature_set_value , and decc$feature_show_all .

Return Values

0 Indicates success.

- 1 Indicates an error; errno is set.

decc$feature_show_all

Displays all feature values for all feature names.

Format

#include <unixlib.h>
int decc$feature_show_all (void);

Description

The decc$feature_show_all function displays to stdout all values for all feature names.
On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_get , decc$feature_get_index , decc$feature_get_name , decc$feature_get_value , decc$feature_set , decc$feature_set_value , and decc$feature_show .

Return Values

0 Indicates success.

- 1 Indicates an error; errno is set.

decc$fix_time

Converts OpenVMS binary system times to UNIX binary times.

Format

#include <unixlib.h>
unsigned int decc$fix_time (void *vms_time);

Argument

vms_time
The address of a quadword containing an OpenVMS binary time:
unsigned int quadword[2]; unsigned int *vms_time = quadword;

Description

The decc$fix_time routine converts an OpenVMS binary system time (a 64-bit quadword containing the number of 100-nanosecond ticks since 00:00 November 17, 1858) to a UNIX binary time (a longword containing the number of seconds since 00:00 January 1, 1970). This routine is useful for converting binary times returned by OpenVMS system services and RMS services to the format used by some HP C RTL routines, such as ctime and localtime .

Return Values

x A longword containing the number of seconds since 00:00 January 1, 1970.

( unsigned int )( - 1) Indicates an error. Be aware, that a return value of ( unsigned int )( - 1) can also represent a valid date of Sun Feb 7 06:28:15 2106.

Example

#include <unixlib.h>
#include <stdio.h>
#include <starlet.h>  /* OpenVMS specific SYS$ routines)  */

main()
{
unsigned int current_vms_time[2]; /*quadword for OpenVMS time*/
unsigned int number_of_seconds;   /* number of seconds     */

/* first get the current system time */
sys$gettim(&current_vms_time[0]);

/* fix the time */
number_of_seconds = decc$fix_time(&current_vms_time[0]);

printf("Number of seconds since 00:00 January 1, 1970 = %d",
        number_of_seconds);
}

This example shows how to use the decc$fix_time routine in HP C. It also shows the use of the SYS$GETTIM system service.

decc$from_vms

Converts OpenVMS file specifications to UNIX style file specifications.

Format

#include <unixlib.h>
int decc$from_vms (const char *vms_filespec, int action_routine, int wild_flag);

Arguments

vms_filespec
The address of a null-terminated string containing a name in OpenVMS file specification format.
action_routine
The address of a routine that takes as its only argument a null-terminated string containing the translation of the given OpenVMS file name to a valid UNIX style file name.
If the action_routine returns a nonzero value (TRUE), file translation continues. If it returns a zero value (FALSE), no further file translation takes place.
wild_flag
Either 0 or 1, passed by value. If a 0 is specified, wildcards found in vms_filespec are not expanded. Otherwise, wildcards are expanded and each one is passed to action_routine. Only expanded file names that correspond to existing UNIX style files are included.

Description

The decc$from_vms routine converts the given OpenVMS file specification into the equivalent UNIX style file specification. It allows you to specify OpenVMS wildcards, which are translated into a list of corresponding existing files in UNIX style file specification format.

Return Value

x The number of file names that result from the specified OpenVMS file specification.

Example

/* This example must be run as a foreign command */ /* and be supplied with an OpenVMS file specification. */ #include <unixlib.h> #include <stdio.h> int main(int argc, char *argv[]) { int number_found; /* number of files found */ int print_name(); /* name printer */ printf("Translating: %s\n", argv[1]); number_found = decc$from_vms(argv[1], print_name, 1); printf("\n%d files found", number_found); } /* print the name on each line */ print_name(char *name) { printf("\n%s", name); /* will continue as long as success status is returned */ return (1); }
This example shows how to use the decc$from_vms routine in HP C. It produces a simple form of the ls command that lists existing files that match an OpenVMS file specification supplied on the command line. The matching files are displayed in UNIX style file specification format.

decc$match_wild

Matches a string to a pattern.

Format

#include <unixlib.h>
int decc$match_wild (char *test_string, char *string_pattern);

Arguments

test_string
The address of a null-terminated string.
string_pattern
The address of a string containing the pattern to be matched. This pattern can contain wildcards (such as asterisks (*), question marks (?), and percent signs (%) as well as regular expressions (such as the range [a-z]).

Description

The decc$match_wild routine determines whether the specified test string is a member of the set of strings specified by the pattern.

Return Values

1 (TRUE) The string matches the pattern.

0 (FALSE) The string does not match the pattern.

Example

/* Define as a foreign command and then provide */
/* two arguments: test_string, string_pattern.  */

#include <unixlib.h>
#include <stdio.h>
int main(int argc, char *argv[])
{
    if (decc$match_wild(argv[1], argv[2]))
        printf("\n%s matches %s", argv[1], argv[2]);
    else
        printf("\n%s does not match %s", argv[1], argv[2]);
}

decc$record_read

Reads a record from a file.

Format

#include <stdio.h>
int decc$record_read (FILE *fp, void *buffer, int nbytes);

Arguments

fp
A file pointer. The specified file pointer must refer to a file currently opened for reading.
buffer
The address of contiguous storage in which the input data is placed.
nbytes
The maximum number of bytes involved in the read operation.

Description

The decc$record_read function is specific to OpenVMS systems and should not be used when writing portable applications.
This function is equivalent to the read function, except that the first argument is a file pointer, not a file descriptor.

Return Values

x The number of characters read.

- 1 Indicates a read error, including physical input errors, illegal buffer addresses, protection violations, undefined file descriptors, and so forth.

decc$record_write

Writes a record to a file.

Format

#include <stdio.h>
int decc$record_write (FILE *fp, void *buffer, int nbytes);

Arguments

fp
A file pointer. The specified file pointer must refer to a file currently opened for writing or updating.
buffer
The address of contiguous storage from which the output data is taken.
nbytes
The maximum number of bytes involved in the write operation.

Description

The decc$record_write function is specific to OpenVMS systems and should not be used when writing portable applications.
This function is equivalent to the write function, except that the first argument is a file pointer, not a file descriptor.

Return Values

x The number of bytes written.

- 1 Indicates errors, including undefined file descriptors, illegal buffer addresses, and physical I/O errors.

decc$set_child_default_dir (ALPHA, I64)

Sets the default directory for a child process spawned by a function from the exec family of functions.

Format

#include <unixlib.h>
int decc$set_child_default_dir (const char *default_dir);

Arguments

default_dir
The default directory specification for child processes, or NULL.

Description

By default, child processes created by one of the exec family of functions inherit the default (working) directory of their parent process.
The decc$set_child_default_dir function lets you set the default directory for a child process. After calling decc$set_child_default_dir , newly spawned child processes have their default directory set to default_dir as they begin execution. The default_dir argument must represent a valid directory specification, or results of the call are unpredictable (subsequent calls to the child process might fail without notification). Both OpenVMS and UNIX style file specifications are supported for this function call.
You can reestablish the default behavior by specifying default_dir as NULL. Subsequently, newly created child processes will inherit their parent's working directory.

Return Values

0 Successful completion. The new inherited default directory was established.

- 1 Indicates failure. No new default directory was established for child processes. The function sets errno to one of the following values:

ENOMEM -- Insufficient memory
ENAMETOOLONG -- default_dir is too long to issue the required SET DEFAULT command.

decc$set_child_standard_streams

For a child spawned by a function from the exec family of functions, associates specified file descriptors with a child's standard streams: stdin , stdout , and stderr .

Format

#include <unixlib.h>
int decc$set_child_standard_streams (int fd1, int fd2, int fd3);

Arguments

fd1
The file associated with this file descriptor in the parent process is associated with file descriptor number 0 ( stdin ) in the child process. If - 1 is specified, the file associated with the parent's file descriptor number 0 is used (the default).
fd2
The file associated with this file descriptor in the parent process is associated with file descriptor number 1 ( stdout ) in the child process. If - 1 is specified, the file associated with the parent's file descriptor number 1 is used (the default).
fd3
The file associated with this file descriptor in the parent process is associated with file descriptor number 2 ( stderr ) in the child process. If - 1 is specified, the file associated with the parent's file descriptor number 2 is used (the default).

Description

The decc$set_child_standard_streams function allows mapping of specified file descriptors to the child's stdin/stdout/stderr streams, thereby compensating, to a certain degree, the lack of a real fork function on OpenVMS systems.
On UNIX systems, the code between fork and exec is executed in the context of the child process:
parent: create pipes p1, p2 and p3 fork child: map stdin to p1 like dup2(p1, stdin); map stdout to p2 like dup2(p2, stdout); map stderr to p3 like dup2(p3, stderr); exec (child reads from stdin and writes to stdout and stderr) exit parent: communicates with the child using pipes
On OpenVMS systems, the same task could be achieved as follows:
parent: create pipes p1, p2 and p3 decc$set_child_standard_streams(p1, p2, p3); vfork exec (child reads from stdin and writes to stdout and stderr) parent: communicates with the child using pipes
Once established through the call to decc$set_child_standard_streams , the mapping of the child's standard streams remains in effect until explicitly disabled by one of the following calls:
decc$set_child_standard_streams(-1, -1, -1);
Or:
decc$set_child_standard_streams(0, 1, 2);
Usually, the child process inherits all its parent's open file descriptors. However, if file descriptor number n was specified in the call to decc$set_child_standard_streams , it is not inherited by the child process as file descriptor number n; instead, it becomes one of the child's standard streams.

Notes

Standard streams can be redirected only to pipes.
If the parent process redefines the DCL DEFINE command, this redefinition is not in effect in a subprocess with user-defined channels. The subprocess always sees the standard DCL DEFINE command.
It is the responsibility of the parent process to consume all the output written by the child process to stdout and stderr . Depending on how the subprocess writes to stdout and stderr ---in wait or nowait mode---the subprocess might be placed in LEF state waiting for the reader. For example, DCL writes to SYS$OUTPUT and SYS$ERROR in a wait mode, so a child process executing a DCL command procedure will wait until all the output is read by the parent process.

Recommendation: Read the pipes associated with the child process' stdout and stderr in a loop until an EOF message is received, or declare write attention ASTs on these mailboxes.
The amount of data written to SYS$OUTPUT depends on the verification status of the process (SET VERIFY/NOVERIFY command); the subprocess inherits the verification status of the parent process. It is the caller's responsibility to set the verification status of the parent process to match the expected amount of data written to SYS$OUTPUT by the subprocess.
Some applications, like DTM, define SYS$ERROR as SYS$OUTPUT. If stderr is not redefined by the caller, it is set in the subprocess as the parent's SYS$ERROR, which in this case translates to the parent's SYS$OUTPUT.

If the caller redefines stdout to a pipe and does not redefine stderr , output sent to stderr goes to the pipe associated with stdout , and the amount of data written to this mailbox may be more than expected. Although redefinition of any subset of standard channels is supported, it is always safe to explicitly redefine all of them (or at least stdout and stderr ) to avoid this situation.
For a child process executing a DCL command procedure, SYS$COMMAND is set to the pipe specified for the child's stdin so that the parent process can feed the child requesting data from SYS$COMMAND through the pipe. For DCL command procedures, it is impossible to pass data from the parent to the child by means of the child's SYS$INPUT because for a command procedure, DCL defines SYS$INPUT as the command file itself.

Return Values

x The number of file descriptors set for the child. This number does not include file descriptors specified as - 1 in the call.

- 1 indicates that an invalid file descriptor was specified; errno is set to EBADF.

Example


parent.c
========

#include <stdio.h>
#include <string.h>
#include <unistd.h>

int decc$set_child_standard_streams(int, int, int);

main()
{
    int fdin[2], fdout[2], fderr[2];
    char msg[] = "parent writing to child's stdin";
    char buf[80];
    int nbytes;

    pipe(fdin);
    pipe(fdout);
    pipe(fderr);

    if ( vfork() == 0 ) {
        decc$set_child_standard_streams(fdin[0], fdout[1], fderr[1]);
      execl( "child", "child" );
    }
    else {
        write(fdin[1], msg, sizeof(msg));
        nbytes = read(fdout[0], buf, sizeof(buf));
        buf[nbytes] = '\0';
        puts(buf);
        nbytes = read(fderr[0], buf, sizeof(buf));
        buf[nbytes] = '\0';
        puts(buf);
    }
}

child.c
=======

#include <stdio.h>
#include <unistd.h>

main()
{
    char msg[] = "child writing to stderr";
    char buf[80];
    int nbytes;

    nbytes = read(0, buf, sizeof(buf));
    write(1, buf, nbytes);
    write(2, msg, sizeof(msg));
}

child.com
=========

$ read sys$command s
$ write sys$output s
$ write sys$error "child writing to stderr"

Contents

Index

HP OpenVMS Systems Documentation

HP CRun-Time Library Reference Manual for OpenVMS Systems

decc$feature_get_value

Format

Arguments

index

mode

Description

Return Values

decc$feature_set

Format

Argument

name

mode

value

Description

Return Values

decc$feature_set_value

Format

Arguments

index

mode

value

Description

Return Values

decc$feature_show

Format

Argument

name

Description

Return Values

decc$feature_show_all

Format

Description

Return Values

decc$fix_time

Format

Argument

vms_time

Description

Return Values

Example

decc$from_vms

Format

Arguments

vms_filespec

action_routine

wild_flag

Description

Return Value

Example

decc$match_wild

Format

Arguments

test_string

string_pattern

Description

Return Values

Example

decc$record_read

Format

Arguments

fp

buffer

nbytes

Description

Return Values

decc$record_write

Format

Arguments

fp

buffer

nbytes

Description

Return Values

decc$set_child_default_dir (ALPHA, I64)

Format

Arguments

default_dir

Description

HP C
Run-Time Library Reference Manual for OpenVMS Systems