When issuing FORTRAN, C, or COBOL program calls under OpenVMS, HLI requires that all arguments passed to it are by descriptor. This is the only way for ACCENT R to know parameters such as the argument type and length.
All calls to the HLI on VAX/OpenVMS have the following general forms:
CALL ACCxxx (%DESCR (error_code), options, %DESCR(argument),..., %DESCR(argument))where 'ACCxxx' is an HLI call.
By default, FORTRAN passes character arguments by descriptor, and non-character arguments by reference (the address of the value).
When the argument being passed is not character, you must use the FORTRAN function "%DESCR", to change the form of the argument passing. You include this function as part of the CALL statement. Each non-character argument must be preceded by %DESCR.
CALL ACCOPN (%DESCR(IER),'CREATE','DS','ORDER',%DESCR(ORDDES))
CALL 'ACCxxx' USING BY DESCRIPTOR error_code, options, BY DESCRIPTOR argument, ..., BY DESCRIPTOR argument.
where 'ACCxxx' is an HLI call.
When issuing COBOL program calls, you must add the BY DESCRIPTOR function to your CALL statement for non-character arguments. Although COBOL passes some non-character arguments by descriptor, it is best to include the BY DESCRIPTOR function if you have any doubt. By default, COBOL always passes character arguments by descriptor.
CALL 'ACCOPN' USING BY DESCRIPTOR IER, 'CREATE', 'DS', 'ORDER', BY DESCRIPTOR ORDDES.
ACCxxx(&error_code, &options, &arguments);
where ACCxxx is an HLI call.
When issuing C program calls, all arguments are passed with descriptors (including character arguments). The HLI procedure name appears with a list of descriptor/arguments
in parentheses. The descriptors are indicated by a leading ampersand and are separated by commas. The C statement is terminated by a semicolon.
ACCOPN(&ier, &CREATE,&DS,&ORDER,&orddes);
Character arguments require specified descriptors because C uses a null to indicate the end of a word. Attempting to pass character arguments with quotes will cause the program to abort with an access violation.
There are three steps to setting up a descriptor in C:
Define the numeric variable or character pointer (indicated by an asterisk) that will actually contain the value;
Define a struct template for descriptors (this involves "including" a library function <descrip.h> which contains the templates);
Assign values to the template fields. The example below shows how the descriptors are set for the error code and the character argument "DS" shown in the previous example.
#include <descrip.h>
main()long error = 0;
char *ds = "DS";struct dsc$descriptor err, DS;
ier.dsc$w_length = sizeof(long);
ier.dsc$a_pointer = &error;
ier.dsc$b_class = DSC$K_CLASS_S;
ier.dsc$b_dtype = DSC$K_DTYPE_L;DS.dsc$w_length = strlen(ds);
DS.dsc$a_pointer = ds;
DS.dsc$b_class = DSC$K_CLASS_S;
DS.dsc$b_dtype = DSC$K_DTYPE_T;
NOTES: The struct "dsc$descriptor" is a general use template. Consult the listing of the library function (<descrip.h> in this case) that contains the descriptor structs for special templates if needed. Struct fields may vary. The possible DSC$K_xxx values are also specified in the library function.
The following syntax notation conventions are used to describe the syntax of each HLI procedure call:
Optional items are enclosed in [brackets].
An ellipsis (...) means that the arguments within the brackets can be repeated.
Commas, parentheses, and words in UPPER CASE must be coded as shown.
Lower case words are user-defined variable names or strings.
Many of the arguments are used in more than one HLI call. These common arguments are described below.
This argument is returned for every HLI call executed. It will contain a value that can be tested to see if the call was successful when control returns to the host program. If a zero is returned, it means that the call was successful. A list of non-zero error codes is included in Appendix C.
This is first argument in each call and it should be a variable defined as follows:
FORTRAN: type INTEGER DOUBLE PRECISION or REAL variables can be used, but are less efficient.
COBOL: PICTURE 9(9) USAGE IS COMP.
C: LONG variable type
This is the second argument in each call. Each option has a name and a corresponding number. Options are specified as a text string or as a numeric variable:
Options specified as strings are enclosed in quotes. To specify multiple options in string form, separate them with plus signs inside the quotation marks. Intervening blanks are not allowed. If specified as a string, options can be:
FORTRAN: a literal string in 'single' quotes.
COBOL: a literal string in 'single' or "double" quotes, or a USAGE IS DISPLAY variable.
C: A literal string is assigned to a CHAR variable which is then tied to a descriptor structure. The descriptor is referenced with an ampersand in the HLI call.
If specified as a number, options can be:
FORTRAN: a zero (%DESCR(0)) or a variable of type INTEGER.
COBOL: a zero (BY DESCRIPTOR 0) or a USAGE IS COMP variable.
C: Integer values are assigned to LONG type variables. Decimal values are assigned to DOUBLE type variables. The numeric variables are then tied to a descriptor structure. The descriptor is referenced with an ampersand in the HLI call.
Each option can be specified only once. To use the default options, a value of zero must be given.
An option name can be translated to its corresponding number with the ACCKWD call. If an HLI procedure is called frequently, using keyword numbers reduces execution time, since the keyword needs to be looked up only once. Two or more options can be specified in a single call by adding the values of the desired options after translating the option to a number with ACCKWD. See the description of the ACCKWD call for more information.
There is also an argument for the ACCOPN procedure called allow_options that follows the same rules as above.
The HUSH option is valid in every call. If the HUSH option is specified, ERROR and WARNING messages are suppressed. The first argument, error_code, will be non-zero whenever an ERROR occurs, regardless of whether HUSH was specified.
The TRACE and NOTRACE options are also valid in every call. If the TRACE option is specified, the values of all the arguments in that procedure call will be printed at execution time. Tracing can also be turned on by placing a non-zero value in the system field "@HLI_TRACE". See the example under the Error Handling and Debugging Tools.
The NOTRACE option suppresses tracing regardless of the value in @HLI_TRACE.
This argument is a number returned from the ACCOPN call that you use in subsequent calls to identify a specific Data Set, Data Index, or DBL.
This argument should be declared as follows:
FORTRAN: INTEGER
COBOL: PICTURE 9(9) USAGE IS COMP
C: LONG
Other variable types can be used, but it will take additional execution time for conversion.
This argument specifies a name. These types of arguments have the suffix "_name" as shown in the examples below:
dbl_name
field_name
domain_name
object_name
For these types of arguments, the following rules apply:
The argument is a left-justified character string.
The string must contain no blanks, except to terminate the string.
Lowercase letters are equivalent to uppercase letters.
The string may contain any valid ASCII characters.
The length of the string must not exceed 40 characters.
Names are returned from calls left-justified and padded with blanks.
The variable must be defined in the program as follows:
These types of arguments have the suffix "_string" as shown in the examples below:
command_string
object_type_string
This argument is a left-justified character string. The string may contain any valid ASCII characters. The variable must be specified in the procedure call as follows.