Procedure Call Descriptions

ACCCLS

This call closes a Data Set, Data Index , or Data Base Library object specified by the designator argument. Closing the Data Set, Data Index, or DBL includes the following functions:

If there are records that have been created or changed that are in a buffer and have not yet been written to the Data Set, those records are written by ACCCLS.
All associations established by the DEFER option of ACCLOA or ACCSTO for this Data Set, Data Index, or DBL object are removed.
Data channels used by this Data Set, Data Index, or DBL object are released to the system.
Memory allocated for that Data Set, Data Index, or DBL object is marked as "available" for subsequent HLI use.

SYNTAX

CALL ACCCLS (error_code, options [ , designator])

error_code

is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.

options

specifies options for this call:

ALL - close all Data Sets objects.

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

DISCARD - if the file was open for CREATE only, discard the new generation version of the file.

designator

is the number returned from the ACCOPN call that identifies the Data Set, Data Index, or DBL object. This argument, if specified, will be ignored if the ALL option is specified. This argument must be specified if the ALL option is omitted, and ACCCLS will change the value of designator to zero.

NOTES: The Data Set, Data Index, or DBL object must be closed by ACCCLS, otherwise one or more of the following problems may occur:

The file will not be closed, thus barring further access to the Data Set and/or Data Index object until the file is closed by the system.

Updating of the Data Set and/or Data Index object may not be completed; some (or all) of the records output by ACCPUT or ACCCRE may be left in a buffer and never be written.

During the execution of the host program, memory and data channels used by Data Set, Data Index, or DBL objects that are not closed are not available for other uses. For examples (See CALL #7 in comprehensive comments.)

FORTRAN Example:

CALL ACCCLS (%descr(err), %descr(set0), %descr(stds))

COBOL Example:

CALL 'ACCCLS' USING BY DESCRIPTOR ERROR-CODE, BY DESCRIPTOR SET-TO-0,

BY DESCRIPTOR STORES-DS.

C Example:

ACCCLS(&err, &SET_0, &st_set);

ACCCMD

This call executes any ACCENT R Interactive Command Language. The commands can be specified in the call itself, or, if the option COMMAND is included in the call, the user can enter commands from the terminal.

SYNTAX

CALL ACCCMD (error_code, options [ , command_string..., command_string])

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

COMMAND - let the user enter input when command_string has been completely read

command_string

specifies the command to execute. This argument can be omitted if the COMMAND option is specified and this argument is given, the specified command(s) are executed before the user is allowed to enter commands. If the COMMAND option is not specified, a PAUSE command is automatically inserted after the last command in command_string has executed. If multiple "command_string " arguments are given, a carriage return is supplied automatically between argument strings, unless the command_string argument is terminated with an ampersand (&).

NOTES: If the COMMAND option is specified, the program halts during execution and waits for command(s) to be entered from the terminal. The user can enter any number of ACCENT R commands until a QUIT or PAUSE command is given. (Note that this is the only use of the PAUSE command on the VAX). Control then returns to the host program. If control is returned with the ACCENT R PAUSE command, a subsequent call to ACCCMD will not reinitialize ACCENT R.

If the COMMAND option is not specified, all commands to be executed must be included in the ACCCMD call itself. Control is automatically returned to the host program when the last command in the command string has been executed, even if a QUIT or PAUSE command is not given.

It is possible to include both the COMMAND option and a command_string in the call. In that case, all commands contained in the ACCCMD call will be executed before control is passed to the terminal for user entry of commands.

When ACCENT R is called from a ACCCMD call, automatic startup files are NOT executed.

The easiest way to communicate between ACCENT R and the HLI is through System Fields. A single copy of most System Fields is shared between ACCENT R and the HLI.

System Fields can be modified by the host program, then tested and/or modified by ACCENT R through the ACCCMD call. Similarly, System Fields can be modified by ACCENT R through the ACCCMD call, then tested and/or modified by the host program.

If a DBL has been established by the host program, the USE DBL and CREATE DBL commands cannot be used in ACCENT R.

If there are errors in the commands that come from this call, control is returned to the host program.

Examples (See CALL #8 in comprehensive example comments.)

FORTRAN Example: (Note: multiple lines require a continuation indicator in column 6.)

CALL ACCCMD(%descr(err),'command','OSQL INSERT NISDEMO:SALES_DBM2 WITH
WINDOW','QUIT')

COBOL Example:

CALL 'ACCCMD' USING BY DESCRIPTOR ERROR-CODE,'COMMAND','OSQL INSERT
NISDEMO:STORES_DBM2 WITH WINDOW','QUIT'.

C Example:

ACCCMD(&err, &COMMAND, &OSQL1, &QUIT);

ACCCRE

This call creates a new record in a Data Set object. The Data Set object must be opened for APPEND, UPDATE, or CREATE. All of the fields in the record should be given values using ACCSTO, or by using ACCRDY with the WITH option. If the Data Set object has record types, the first field moved into the record after a call to ACCRDY must be the field declared as RECORD ID in the Schema Definition. ACCRDY must be called before each call to ACCCRE in order to clear the record area. ACCRDY must be called before storing a value into the RECORD ID field.

SYNTAX

CALL ACCCRE (error_code, options, designator)

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call: HUSH - do not print error and warning messages. IMMEDIATE - create the ACCENT R record immediately. NOTRACE - do not print argument values at execution time. TRACE - print argument values at execution time.
designator	is the number returned from the ACCOPN call that identifies the Data Set or Data Index object.

NOTES: Field values may be copied into the record by calling ACCSTO before calling ACCCRE. If ACCSTO has been called with the DEFER option, the field values specified in that ACCSTO call are copied into the record by ACCCRE. These values could overwrite the field values (if any) copied by an ACCSTO call without the DEFER option.

If a Data Index object has been specified in ACCOPN, all affected domains of the Data Index object are modified. Records created by ACCCRE are immediately made available for subsequent ACCGET calls.

Examples (See CALL #11 in comprehensive example comments.)

FORTRAN Example:

CALL ACCCRE(%descr(err), %descr(set0), %descr(sds))

COBOL Example:

CALL 'ACCCRE' USING BY DESCRIPTOR ERROR-CODE, BY DESCRIPTOR
SET-TO-0, BY DESCRIPTOR SALES-DS.

C Example:

ACCCRE(&err, &SET_0, &s_set);

ACCDBL

This call declares the Data Base Library (DBL to be used). All objects (Data Sets, Schema Definitions, and Data Indexes) must have been previously created via the ACCENT R DEFINE and CREATE commands.

SYNTAX

CALL ACCDBL (error_code, options [ , dbl_name] )

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

dbl_name

specifies the name of the DBL. If dbl_name is omitted, the current DBL will be released.

NOTES: A subsequent call to ACCDBL requires that all Data Set objects be closed with ACCCLS. If any Data Set objects are not closed, ACCDBL will automatically call ACCCLS with the ALL option. ACCDBL "closes" the DBL specified in the previous ACCDBL call.

Examples (See CALL #3 in comprehensive example comments.)

FORTRAN Example:

CALL ACCDBL (%descr(err), %descr(set0), 'books')

COBOL Example:

CALL 'ACCDBL' USING BY DESCRIPTOR ERROR-CODE,
BY DESCRIPTOR SET-TO-0, 'BOOKS'.

C Example:

ACCDBL(&err, &SET_0, &BOOKS);

ACCDEL

This call deletes the current record from the Data Set object. The record to be deleted must have been read using ACCGET and the record locked using the 'LOCKED' option. ACCDEL requires that the ACCOPN call specified the UPDATE or DELETE option. This requirement corresponds to the RELATE statement in the Control Section of a Process Module object.

SYNTAX

CALL ACCDEL (error_code, options, designator)

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

IMMEDIATE - delete the ACCENT R record immediately.

NOTRACE - do not print argument values at execution time.

TRACE - print argument values at execution time.

designator

is the number returned from the ACCOPN call that identifies the Data Set or Data Index.

NOTES: The record is not actually removed from the Data Set object, rather it is marked in such a way that the record will be ignored when either ACCENT R or HLI subsequently reads from the Data Set object ("in-place delete").

If a Data Index object has been specified (in ACCOPN), all affected domains of the Data Index object are modified. The ACCDEL call cannot be used with a Data Set object if its associated SD (Schema Definition) object specified the DISALLOW IN PLACE DELETES option.

Examples (See CALL #17 in comprehensive example comments.)

FORTRAN Example:

CALL ACCDEL (%descr(err), 'immediate', %descr(ds))

COBOL Example:

CALL 'ACCDEL' USING BY DESCRIPTOR ERROR-CODE,'IMMEDIATE',
BY DESCRIPTOR SALES-DS.

C Example:

ACCDEL(&err, &IMM, &sales_ds);

ACCEND

This call terminates the HLI. ACCEND must be the last HLI procedure called before leaving the host program.

SYNTAX

CALL ACCEND (error_code [ , options] )

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

Examples (See CALL #12 in comprehensive example comments.)

FORTRAN Example:

CALL ACCEND (%descr(err))

COBOL Example:

CALL 'ACCEND' USING BY DESCRIPTOR ERROR-CODE.

C Example:

ACCEND(&err);

ACCFRE

This call frees all queued records in a Data Set object. See the FREE statement in the ACCENT R Reference Manual for more information.

SYNTAX

CALL ACCFRE (error_code, options [ ,designator] )

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

ALL - free all queued records in the specified Data Set. This option is required.

designator

is the number returned from the ACCOPN call that identifies the Data Set or Data Index object. If this argument is omitted, the ACCFRE call will free records from all Data Sets that are opened.

Examples (See CALL #18 in comprehensive example comments.)

FORTRAN Example:

CALL ACCFRE (%descr(err), 'all', %descr(ds))

COBOL Example:

CALL 'ACCFRE' USING BY DESCRIPTOR ERROR-CODE,'ALL',BY DESCRIPTOR SALES-DS.

C Example:

ACCFRE(&err, &ALL, &sales_ds);

ACCGET

This form of ACCGET retrieves a record from a Data Set object. Field values may be retrieved from the Data Set record by calling ACCLOA after calling ACCGET, or by calling ACCLOA with the DEFER option before calling ACCGET. If ACCLOA has been called with the DEFER option, the field values specified in that ACCLOA call are automatically copied into the specified host program variables by ACCGET.

The ACCGET call can perform all the functions of the GET statement in a Process Module. See the ACCENT R Reference Manual for a description of the GET statement.

SYNTAX

CALL ACCGET (error_code, options, designator, domain_name, [ , by_value ?… by_value])

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call. The following options are not allowed unless a Data Index object has been specified with ACCOPN: FIT, HIGH, LOW, MATCH. HUSH- do not print error and warning messages. TRACE - print argument values at execution time. NOTRACE - do not print argument values at execution time. ADDRESS* FIRST* FIT* HIGH* LAST* LOW* MATCH* NEXT*
	NOTINDEXED* PRIOR* RECORD* LOCKED* NOTLOCKED MULTIPLE* NORECORD - look up the specified key value in a Data Index without retrieving the associated Data Set record. See the GET* statement description in the ACCENT R Reference Manual.
designator	is the number returned from the ACCOPN call that identifies the Data Set or Data Index object.
domain_name	specifies the name of the Data Index domain to be used to find this record. The first domain will be used if this argument is set to 0. Set this argument to ' ' (blank) if there is no RAM data index being used.
by_value	should be repeated for each key field in the specified domain of the Data Index, unless a partial key (left subset) retrieval is desired. See the ACCENT R Reference Manual for a description of the "BY \\value\\" clause in the GET statement for more details.
by_value	specifies the key value to be matched when using the key matching form of ACCGET. This argument must be a variable containing a value or a literal constant. HLI uses the value of this variable, but never changes it.

If the RECORD option has been specified, use this argument to specify the record number of the record to be retrieved. This option requires that the ACCOPN call specified a Data Set, and not a Data Index object. This argument is subject to the restrictions described in the ACCLOA call for the target_variable argument.

If the ADDRESS option has been specified, use this argument to specify the record address. This argument is subject to the restrictions described in the ACCLOA call for the target_variable argument.

Whenever using the direct access form of the ACCGET call, either the RECORD option or the ADDRESS option, all records in the Data Set object must have the same length. ACCENT R cannot calculate the specified record address unless all records are the same length.

Examples (See CALL #6 in comprehensive example comments.)

FORTRAN Example: (Note: multiple lines require a continuation indicator in column 6.)

CALL ACCGET(%descr(err),'match +hush',%descr(sds), ' ',1%descr(shost))

COBOL Example:

CALL 'ACCGET' USING BY DESCRIPTOR ERROR-CODE, 'MATCH+HUSH',
BY DESCRIPTOR STORES-DS, ' ', BY DESCRIPTOR D-STORE-CODE.

C Example:

ACCGET(&err, &MHUSH, &st_set, &BK, &d_s_code);

ACCGET

Read a DBL Entry

This form of the ACCGET call retrieves the entries in a DBL in a record format. The DBL is opened using the ACCOPN call, specifying "GET" as an option (since it can only be accessed as read-only) and "DBL" as the object type. See the discussion "GET Statement for Data Base Library Access" in the ACCENT R Reference Manual.

SYNTAX

CALL ACCGET (error_code, DBL + options, designator, ' ', [ , object_type_string][ ,object_name])

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call: DBL - Required option to specify DBL access. HUSH - do not print error and warning messages. TRACE - print argument values at execution time. NOTRACE - do not print argument values at execution time. FIRST+ENTRY* NEXT+ENTRY* ENTRY* FIRST+TEXT* (Note that TEXT without FIRST or NEXT is not valid.) NEXT+TEXT* (Note that TEXT without FIRST or NEXT is not valid.) *See "GET Statement for DBL Access" in the ACCENT R Reference Manual.
designator	is the number returned from the ACCOPN call that identifies the DBL.
' '	A blank must appear in place of the domain_name argument.
object_type_string	specifies the type of DBL object. The value can be any valid object: SD, DS, CM, PM, CS, CF, DI, ID, GS, SF, SI. This argument must be included if the option ENTRY is used, and may be included if the option FIRST ENTRY or NEXT ENTRY is used. It cannot be included if the option FIRST TEXT or NEXT TEXT is used.
object_name	is the name of the DBL object to be retrieved. This argument must be included if the option ENTRY is used, but may not be included with any of the other retrieval options.

Examples (See CALL #14 in comprehensive example comments.)

FORTRAN Example: (Note: multiple lines require a continuation indicator in column 6.)

CALL ACCOPN (%descr(err),'get','dbl','books',%descr(dbl))
CALL ACCGET (%descr(err), 'dbl+trace+entry', %descr(dbl),
1         ' ', 'sd', 'sales_dbm2')
CALL ACCLOA (%descr(err),'trace',%descr(dbl),
1         'entry.type',%descr(etype),
2         'entry.name',%descr(ename),
3         'create.time',%descr(etime))
PRINT *, 'DBL Object Type: ', etype
PRINT *, 'DBL Object Name: ', ename
PRINT *, 'Create Time: ', etime

COBOL Example:

CALL 'ACCOPN' USING BY DESCRIPTOR ERROR-CODE,'GET','DBL','BOOKS',
BY DESCRIPTOR BOOKS-DBL.

CALL 'ACCGET' USING BY DESCRIPTOR ERROR-CODE,'DBL+TRACE+ENTRY',
BY DESCRIPTOR BOOKS-DBL, ' ', 'SD', 'SALES_DBM2'.

CALL 'ACCLOA' USING BY DESCRIPTOR ERROR-CODE, 'TRACE', BY
DESCRIPTOR BOOKS-DBL,
'ENTRY.TYPE', BY DESCRIPTOR E-TYPE,
'ENTRY.NAME', BY DESCRIPTOR E-NAME,
'CREATE.TIME',. BY DESCRIPTOR E-TIME.

DISPLAY 'DBL object type: ', E-TYPE.

DISPLAY 'DBL object name: ', E-NAME.

DISPLAY 'Create time: ', E-TIME.

C Example:

ACCOPN(&err, &GET, &BASE, &BOOKS, &book_dbl);
ACCGET(&err, &ENTRY, &book_dbl, &BK, &SD, &DBM2);
ACCLOA(&err, &TRACE, &book_dbl,
    &ENTRY_T, &e_type,
    &ENTRY_N, &e_name,
    &CREATE, &e_time);
printf("DBL OBJECT TYPE: %s \n", i_type);
printf("DBL OBJECT NAME: %s \n", i_name);
printf("CREATE TIME: %ld \n \n", i_time);

ACCINI

This call initializes the HLI environment for any language. ACCINI is always the first HLI call issued in a program. ACCINI defaults to FORTRAN if the programming language is not specified. Note: With the use of ACCINI, the language dependent initialization procedures (ACCCOB, ACCFOR, ACCMAC) have become obsolete.

SYNTAX

CALL ACCINI (error_code [, options[, "language"]])

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

"language"

specifies the language that is using the HLI procedures

Examples (See CALL #1 in comprehensive example comments.)

FORTRAN Example:

CALL ACCINI (%descr(err), 'trace', 'fortran')

COBOL Example:

CALL 'ACCINI' USING BY DESCRIPTOR ERROR-CODE,'TRACE','COBOL'.

C Example:

ACCINI(&err, &TRACE, &C);

ACCKWD

This call sets up host program variables that can subsequently be used as an option in a HLI procedure call. The value returned by ACCKWD is such that it can be added to the values of other options (using COMPUTE). Each value can be specified only once. This allows the specification of multiple options in a single call.

If an error occurs while processing a keyword, subsequent keywords in the same ACCKWD call will not be processed.

SYNTAX

CALL ACCKWD (error_code, options, keyword_string, keyword_variable
[ ... , keyword_string, keyword_variable])

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call: HUSH - do not print error and warning messages. TRACE - print argument values at execution time. NOTRACE - do not print argument values at execution time.
keyword_string	is a string containing the keyword. The following is a list of valid keywords:
		ADDRESS ALL APPEND APPENDING ASSUME COMMAND CREATE DBL DEFER DELETE DISCARD ENTRY FIRST FIT GET HIGH HUSH IMMEDIATE INPUT	LAST LOCKED LOW MATCH MEMORY MULTIPLE NEXT NOFORM NORECORD NOTINDEXED NOTRACE PRIOR PUT RECORD TEXT TRACE UPDATE WAIT WITH
keyword_variable	is a host program variable to be used as an option in a subsequent call. This argument should be declared: FORTRAN: INTEGER COBOL: PIC 9(9) USAGE IS COMP. C: long

Examples (See CALL #15 in comprehensive example comments.)

FORTRAN Example: (NOTE: multiple lines require a continuation indicator in column 6.)

      CALL ACCKWD (%descr(err), 'trace',
1              'match', %descr(xmatch),
2              'hush', %descr(xhush),
3              'locked', %descr(xlok))
      xopt = xmatch + xhush + xlok

COBOL Example:

CALL 'ACCKWD' USING BY DESCRIPTOR ERROR-CODE, 'TRACE',

      'MATCH',BY DESCRIPTOR X-MATCH,

      'HUSH', BY DESCRIPTOR X-HUSH,

      'LOCKED', BY DESCRIPTOR X-LOCKED.
COMPUTE X-OPTION = X-MATCH + X-HUSH + X-LOCKED.

C Example:

ACCKWD(&err, &TRACE,

   &MATCH, &x_match,

   &HUSH, &x_hush,

   &LOCKED, &x_lock);
x_opt = x_match + x_hush + x_lock;

ACCLOA

This call retrieves the value of a particular field or list of fields. This call must be preceded by an ACCGET call or by an ACCRDY call to make a record available for processing, unless the DEFER option is specified.

SYNTAX

CALL ACCLOA (error_code, options, designator, field_name [ , occurs_range, 0], target_variable [..., field_name [ , occurs_range, 0], target_variable])

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call: HUSH - do not print error and warning messages. TRACE - print argument values at execution time. NOTRACE - do not print argument values at execution time. DEFER - defer the action of this call until ACCGET is called. The action of this call will be performed on every call to ACCGET with the same designator. IMPORTANT: Be extremely cautious when using the DEFER option in a program that is compiled with "inter-statement optimization". Because the compiler has no way of knowing that a subsequent call will use or modify variables specified in this call, you can get unexpected results. By placing variables used with the DEFER option in blank or labeled COMMON, the problem is eliminated. CREATE - the values are to be retrieved from the record area that can be written with a call to ACCCRE. ASSUME - the decimal point in a COBOL COMP field will be in the same position as in the corresponding field in the ACCENT R Schema Definition.
designator	is the number returned from the ACCOPN call that identifies the Data Set, Data Index, or DBL object. Designator can be specified as zero for System Fields.
field_name, occurs_range, target_variable, and string_length	should be repeated for each field being retrieved.
field_name	is the name of the system or Data Set field. The at-sign (@) must be included as part of the name of a System Field. If the System Field has an implicit OCCURS clause, such as @INTEGER and @STRING, the occurs_range arguments are required.
occurs_range	is required if the field has an OCCURS clause. It specifies which element of the field is being loaded. This argument should be declared: FORTRAN: INTEGER COBOL: PIC 9(9) USAGE IS COMP If an occurs_range is specified, it must be followed by a zero argument. See the subsection called FIELDS WITH OCCURS for a complete description of how to use this argument.
target_variable	is the variable where the value for the previously named field is to be stored. This argument specifies the area in the host program that is to contain the value of a field from a record. The original value of this variable is ignored by the HLI. When control returns to the host program, the variable will contain a new value. The type of the argument must be appropriate for the ACCENT R field type, according to the following tables:

FORTRAN:

ACCENT R Data Type	FORTRAN Data Type
CHAR	CHARACTER
ALPHA	CHARACTER
INT	INTEGER INTEGER*4
REAL	REAL REAL4 REAL8
FLOAT	DOUBLE PRECISION
DATE	INTEGER*4
FULLDATE	INTEGER*4
BIT	INTEGER*4

Data types not currently supported:

INTEGER*2

REAL*16

ACCENT R Data Type	C Data Type
CHAR	char
ALPHA	char
INT	long integer*
REAL	double
FLOAT	double float*

* not used with VAX

COBOL:

ACCENT R Data Type	COBOL Format
CHAR	PIC X(n) SAGE DISPLAY.
ALPHA	PIC X(n) SAGE DISPLAY.
INT	PIC 9(n) USAGE DISPLAY. PIC 9(n) USAGE COMP. 5<=n<=9
REAL (no PIC with COMP)	PIC 9(n) USAGE DISPLAY. USAGE COMP-1.
FLOAT (no PIC with COMP)	PIC 9(n) USAGE DISPLAY. USAGE COMP-2.
DATE	PIC 9(8) USAGE DISPLAY. PIC 9(8) USAGE COMP.
FULLDATE	PIC 9(8) USAGE DISPLAY. PIC 9(8) USAGE COMP.
BIT	PIC 9(n) USAGE DISPLAY.

Data types not currently supported:

word integer (2 bytes)

quad integer (8 bytes)

Note that the HLI performs all type conversions before moving the data to host program variables:

"I," "D," "F," "BB," and "SB" fields are converted to fixed point binary integers.

"N," "V," and "R" fields are converted to floating point binary integers.

Examples (See CALL #5 in comprehensive example comments.)

FORTRAN Example: (Note: multiple lines require a continuation indicator in column 6.)

   CALL ACCLOA (%descr(err), 'defer', %descr(stds),
1        'store_code', %descr(stst),
2        'store_name', %descr(name),
3        'store_address', %descr(addr),
4        'city', %descr(city),
5        'state', %descr(state),
6        'zip', %descr(zip),
7        'country', %descr(kuntry))

COBOL Example:

CALL 'ACCLOA' USING BY DESCRIPTOR ERROR-CODE, 'DEFER',
   BY DESCRIPTOR STORES-DS,
   'STORE_CODE', BY DESCRIPTOR SS-CODE,
   'STORE_NAME', BY DESCRIPTOR STORE-NAME,
   'STORE_ADDRESS', BY DESCRIPTOR ADDRESS,
   'CITY', BY DESCRIPTOR CITY,
   'STATE', BY DESCRIPTOR STATE,
   'ZIP', BY DESCRIPTOR ZIP,
   'COUNTRY', BY DESCRIPTOR COUNTRY.

C Example:

ACCLOA(&err, &DEFER, &st_set,
            &STORE, &st_store,
            &S_NAME, &st_name,
            &S_ADD,&st_add,
            &S_CITY, &st_city,
            &S_STATE, &st_state,
            &S_ZIP, &st_zip,
            &S_COUNT, &st_count);

ACCLOK

The ACCLOK call is used to reserve all records in the Data Set for exclusive use. See the LOCK statement in the ACCENT R Reference Manual for a detailed description.

NOTE: ACCDEL requires that a record be locked before it can be deleted. This is accomplished through the locked option in ACCGET rather than ACCLOK.

SYNTAX

CALL ACCLOK (error_code, options, designator)

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

ALL - lock all records in the specified Data Set. This option is required.

designator

is the number returned from the ACCOPN call that identifies the Data Set or Data Index object.

Examples (See CALL #16 in comprehensive example comments.)

FORTRAN Example:

CALL ACCLOK (%descr(err), 'all', %descr(ds))

COBOL Example:

CALL 'ACCLOK' USING BY DESCRIPTOR ERROR-CODE,'ALL',BY DESCRIPTOR
SALES-DS.

C Example:

ACCLOK(&err, &ALL, &sales_ds);

ACCOPN

This call opens a Data Set or Data Index object for input, output, append, or update. This call can also open a DBL for input.

When using HLI with Simultaneous Update, deadly embraces may occur unless all programs open the shared files in the same order.

SYNTAX

CALL ACCOPN (error_code, options, object_type_string, object_name, designator, allow_options)

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call: HUSH - do not print error and warning messages. TRACE - print argument values at execution time. NOTRACE - do not print argument values at execution time. APPEND/ING/ - ad records to the Data Set and/or Data Index object, but do not destroy the old data (if any). CREATE - open the Data Set or Data Index object for creating records. The previous contents of the Data Set object will be overwritten. GET - open the Data Set or Data Index object for reading only. See the discussion of the RELATE statement in the ACCENT R Reference Manual. UPDATE - open the Data Set and/or Data Index object for reading, replacing, and creating records. Automatically implies the APPEND and GET and DELETE and PUT options. PUT - declare the Data Set for accepting changed records. See the discussion of the RELATE statement in the ACCENT R Reference Manual.
	DELETE - declare the Data Set object for deleting records. See the RELATE statement in the ACCENT R Reference Manual. NOFORM - do not form the Data Index (if any), even if it is no longer current. If the NOFORM option is specified, and the index is not current, the ACCOPN call will fail. The following table shows which combination of options is valid.
	Input only: GET Supersede only: CREATE Input/output (update): GET+PUT GET+DELETE GET+PUT+DELETE GET+PUT+APPEND GET+DELETE+APPEND GET+PUT+DELETE+APPEND UPDATE UPDATE+GET UPDATE+APPEND UPDATE+GET+APPEND
	Append: APPEND GET+APPEND
	This table shows the combinations of the GET, UPDATE, and CREATE options that are appropriate for each type of HLI call: Call Required options in ACCOPN ACCGET GET or UPDATE ACCLOA GET or UPDATE ACCSTO UPDATE or CREATE or APPEND ACCPUT PUT or UPDATE ACCDEL DELETE or UPDATE ACCCRE CREATE
object_type_string	specifies the type of file being opened: DS - Data Set object. DI - use a Data Index object to read the data. DBL - read entries from the DBL.
object_name	is the name of the Data Set, Data Index, or DBL to be opened. The full pathname can be specified, as in ACCENT R.
designator	is the number returned from the ACCOPN call that identifies the Data Set, Data Index, or DBL object. This variable name is used in other HLI calls to specify the Data Set, Data Index or DBL object. Each Data Set, Data Index, or DBL object must have a unique variable name for the designator.
allow_options	specifies the type of access that will be allowed for other programs or interactive users who attempt to use the Data Set while this program has control of it. This option parallels the ALLOWING clause of the RELATE statement. See the discussion of the RELATE statement in the ACCENT R Reference Manual. This argument follows the same rules as the "options" argument. Either text strings or numbers may be used to specify the type of access. ACCKWD can be used to convert text string values to the corresponding numbers. Possible allow_options values are: GET - allow others to access the Data Set object for input. PUT - allow others to access the Data Set object for adding changed records. DELETE - allow others to access the Data Set object for deleting records. APPEND - allow others to append new records to the Data Set object. UPDATE - allow others to read, change, delete, or append new records. WAIT - allow no other users to access the Data Set object while it is opened by this call.
	The following table shows which combination of allow_options is valid: GET GET+PUT GET+DELETE GET+APPEND GET+PUT+DELETE GET+PUT+APPEND GET+DELETE+APPEND GET+PUT+DELETE+APPEND APPEND UPDATE WAIT

Examples (See CALL #4 in comprehensive example comments.)

FORTRAN Example: (NOTE: multiple lines require a continuation indicator in column 6.)

CALL ACCOPN (%descr(err), 'update', 'di',
1' 'nisdemo:sales_dbm2', %descr(sds))

COBOL Example:

CALL 'ACCOPN' USING BY DESCRIPTOR ERROR-CODE, 'UPDATE', 'DI',
'NISDEMO:SALES_DBM2', BY DESCRIPTOR SALES-DS.

C Example:

ACCOPN(&err, &UPDATE, &DI, &s_ds, &s_set);

ACCPUT

This statement updates an existing record. The ACCOPN call must have specified the UPDATE or PUT option. The record to be changed must have been retrieved by ACCGET, which specified the LOCKED option.

Values in the fields of the record are changed using ACCSTO after the ACCGET statement and before the ACCPUT statement. If ACCSTO has been called with the DEFER option, the field values specified in that ACCSTO call are automatically copied into the Data Set object record by ACCPUT. These values could overwrite the field value(s), if any, copied by a subsequent ACCSTO call without the DEFER option.

SYNTAX

CALL ACCPUT (error_code, options, designator)

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

IMMEDIATE - write out changes to the ACCENT R record immediately, without waiting until the buffer is full, or the file is closed with an ACCCLS call.

designator

is the number returned from the ACCOPN call that identifies the Data Set or Data Index object.

NOTES: If the ACCOPN call opened a Data Index object, and a key field is modified, all affected domains of the Data Index object are modified. A domain will also be modified if a field used in an ENTER conditional is changed, and that change causes the record to be added or removed from the domain. If KEY CHANGE NOT ALLOWED was specified in any of the affected domains, then ACCPUT will not change the record if a value is stored into a key field. To change data in fields other than the key field, use the ACCSTO call to store data into those fields only. If DUPLICATES NOT ALLOWED was specified in any of the affected domains, and the key fields are changed to be the same as those of a record already in the domain, then ACCPUT will not change the record.

Examples (See CALL #9 in comprehensive example comments.)

FORTRAN Example:

CALL ACCPUT (%descr(err), %descr(set0), %descr(bds))

COBOL Example:

CALL 'ACCPUT' USING BY DESCRIPTOR ERROR-CODE, BY DESCRIPTOR
SET-TO-0, BY DESCRIPTOR BOOKS-DS.

C Example:

ACCPUT(&err, &SET_0, &b_set);

ACCRDY

This call must be used to clear or initialize a record area before a record is created with ACCCRE. Otherwise, the record will be initialized to values from the record most recently created with ACCRDY for the same Data Set object.

SYNTAX

CALL ACCRDY (error_code, options, designator [ , with_designator] )

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call: HUSH - do not print error and warning messages. TRACE - print argument values at execution time. NOTRACE - do not print argument values at execution time. WITH - initialize the record with the record most recently read from the Data Set specified by with_designator.
designator	is the number returned from the ACCOPN call that identifies the Data Set or Data Index object.
with_designator	is the number returned from the ACCOPN call that identifies the Data Set or Data Index object from which the record is being initialized. The Data Set or Data Index objects specified by designator and with_designator must have the same Schema Definition object. Designator and with_designator can specify the same Data Set or Data Index object. This argument must be omitted unless the WITH option is specified.

NOTES: If a Data Set has multiple record types, ACCRDY must be called before storing a value into the RECORD ID field.

ACCRDY requires that the Data Set object be opened for APPEND, UPDATE, or CREATE.

Examples (See CALL #10 in comprehensive example comments.)

FORTRAN Example:

CALL ACCRDY (%descr(err), %descr(set0), %descr(sds))

COBOL Example:

CALL 'ACCRDY' USING BY DESCRIPTOR ERROR-CODE, BY DESCRIPTOR
SET-TO-0, BY DESCRIPTOR SALES-DS.

C Example:

ACCRDY(&err, &SET_0, &s_set);

ACCSTO

This call stores the value of a particular variable or list of variables into a field(s). The ACCPUT or ACCCRE procedure is used to write the modified record to the Data Set object. If ACCCRE is used, a prior ACCCRE must have been issued, and the ACCSTO call must specify the CREATE option. If ACCPUT is used, a prior ACCGET must have been issued, and the ACCSTO call should not specify the CREATE option.

ACCPUT or ACCCRE must follow any ACCSTO call in order to write the changes to the Data Set object.

ACCSTO requires that the Data Set object be opened for PUT, APPEND, UPDATE, or CREATE.

SYNTAX

CALL ACCSTO (error_code, options, designator, field_name [ , occurs_range, 0],
source_variable [ ... , field_name [ , occurs_range, 0], source_variable ])

error_code	is returned and contains 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 requested function was successful. Refer to Appendix C for a list of the error codes.
options	specifies options for this call: HUSH - do not print error and warning messages. TRACE - print argument values at execution time. NOTRACE - do not print argument values at execution time. DEFER - defer the action of this call until ACCPUT or ACCCRE is called. The action of this call will be performed on every call to ACCPUT or ACCCRE with the same designator. IMPORTANT: Be extremely cautious when using the DEFER option in a program that is compiled with "inter-statement optimization". Because the compiler has no way of knowing that a subsequent call will use or modify variables specified in this call, you can get unexpected results. By placing variables used with the DEFER option in blank or labeled COMMON, the problem is eliminated.
	CREATE - place the values in the record area that can be written with a call to ACCCRE. If the CREATE option is not specified, the values are placed into the record area that can be written with ACCPUT. ASSUME - place the decimal point in a COBOL COMP field in the same position as in the corresponding field in the ACCENT R Schema Definition object.
designator	is the number returned from the ACCOPN call that identifies the Data Set, Data Index, or DBL object. Designator can be specified as zero for System Fields.
field_name, occurs_range, source_variable, and string_length	should be repeated for each field into which data is to be stored. These arguments for ACCSTO are exactly like those for ACCLOA, except that ACCSTO moves the data FROM host program variables to the Data Set fields.
field_name	is the name of the Data Set field or System Field. If designator is zero, this variable can be the name of a System Field. The at-sign (@) must be included as part of the name of a System Field. If the System Field has an implicit OCCURS clause, such as @INTEGER and @STRING, the occurs_range argument is required. If you are storing data in a Data Set that has multiple record types, the record type field must be the first field stored into a new record.
source_variable	is the variable where the value for the previously named field is stored. This argument must be a variable containing a value or a literal constant. HLI uses the value of this variable, but never changes it.
occurs_range	is required if and only if the field has an OCCURS clause in the Schema Definition. It specifies which element of the field is being stored. This argument should be declared as follows: FORTRAN: INTEGER COBOL: PIC 9(9) USAGE IS COMP Other variable types can be used, but there may be a loss of precision and it will take additional execution time for conversion. If an occurs range is specified, it must be followed by a zero argument. See the subsection called "FIELDS_WITH_OCCURS" for a complete description of how to use this argument.

Examples (See CALL #2 in comprehensive example comments.)

FORTRAN Example: (Note: multiple lines require a continuation indicator in column 6.)

CALL ACCSTO (%descr(err), 'trace', %descr(set0), 'HLI_TRACE',
1 %descr(set1))

COBOL Example:

CALL 'ACCSTO' USING BY DESCRIPTOR ERROR-CODE, 'TRACE',
BY DESCRIPTOR SET-TO-0, '@HLI_TRACE', BY DESCRIPTOR SET-TO-1.

C Example:

ACCSTO(&err, &TRACE, &SET_0, &HLI, &SET_1);

ACCVER

This call prints version information about HLI. The information is printed on the terminal, or in the log file from a batch job.

SYNTAX

CALL ACCVER (error_code [ , options] )

error_code

options

specifies options for this call:

HUSH - do not print error and warning messages.

TRACE - print argument values at execution time.

NOTRACE - do not print argument values at execution time.

Examples (See CALL #13 in comprehensive example comments.)

FORTRAN Example:

CALL ACCVER (%descr(err), 'trace')

COBOL Example:

CALL 'ACCVER' USING BY DESCRIPTOR ERROR-CODE, 'TRACE'.

C Example:

ACCVER(&err, &TRACE);