Using the CA-IDMS INFILE Statement

Definition of the CA-IDMS INFILE STATEMENT

If you are unfamiliar with the standard INFILE statement, see SAS Statements: Reference for more information.

A standard INFILE statement specifies an external file to be read by an INPUT statement. A CA-IDMS INFILE statement specifies a subschema, which in turn identifies the CA-IDMS database, records, and elements to be accessed with CA-IDMS calls. Special extensions in the CA-IDMS INFILE statement specify SAS variables and constants that are used to build a CA-IDMS call and to handle the data returned by the call. A subset of the standard INFILE statement options can also be specified in a CA-IDMS INFILE statement.

Use the following syntax when you issue a CA-IDMS INFILE statement:

INFILE SUBSCHname IDMS <options>;

SUBSCHname

specifies the name of the subschema used to communicate with CA-IDMS in the current DATA step. A subschema name is required and must immediately follow INFILE. (A standard INFILE statement would specify a fileref in this position.) You can open only one subschema per DATA step.

IDMS

tells SAS that this INFILE statement refers to a CA-IDMS database. IDMS is required and must follow the subschema name.

options

usually define SAS variables that contain CA-IDMS information used to generate DML calls. These variables are not added automatically to a SAS output data set (that is, they have the status of variables that are dropped). To include the variables in an output SAS data set, create separate variables and assign values to them. The variables do not need to be predefined before specification in the CA-IDMS INFILE statement. SAS defines them automatically with the correct type and length. The following sections describe the options that are valid in the INFILE statement.

CA-IDMS Environment Options

The following options affect how the bind-run call is generated. All of the environment options are optional. If any of the next four options' values should change during the execution of the DATA step, a finish call is executed, followed by a new bind-run call.

DANAME=variable

specifies a SAS variable that contains the logical CA-IDMS database name, as defined in the database name table.

DANODE=variable

specifies a SAS variable that contains the DC/UCF of CA-IDMS where the database is defined. Use this option only if you are running a Distributed Database System.

DCNAME=variable

specifies a SAS variable that contains the name of the CA-IDMS dictionary where the subschema is defined. Use this option only if you are using a subschema that is defined in a dictionary other than the default dictionary.

DCNODE=variable

specifies a SAS variable that contains the DC/UCF system needed to process the database requests. Use this option only if you are running a Distributed Database System.

Other CA-IDMS Options

The following list describes additional options that are available only in the CA-IDMS INFILE statement:

AREA=variable

names a SAS variable that contains the name of the CA-IDMS AREA that you want to access. The AREA must be included in the subschema that was specified in the INFILE statement.

DBKEY=variable

names a SAS variable to which the database record's key, db-key, is assigned after successful execution of an ACCEPT or a RETURN call to the database. A record's db-key can then be used to access a record directly. In this case, the DBKEY variable contains the db-key of the record that you want to access directly, along with FIND or OBTAIN in the FUNC= variable.

ERRSTAT=variable

names a SAS variable to which the CA-IDMS call status is assigned after each CA-IDMS call. If ERRSTAT= is not specified, call status codes are not returned. The variable is a character variable with a length of 4.

It is highly recommended that you check the call status codes that CA-IDMS returns, and this option provides a convenient way to do so. (See Call Status Codes for more information about checking call statuses in CA-IDMS DATA step programs.)

FUNC=variable

names a SAS variable that contains the CA-IDMS call function that is used when the CA-IDMS INPUT statement is executed. The variable must be assigned a valid CA-IDMS call function code before a CA-IDMS INPUT statement is executed. The value of the FUNC= variable can be changed between calls. The valid function calls are BIND, FIND, OBTAIN, ACCEPT, GET, IF, and RETURN. Each of these function calls is described in Specifying DML Function Calls.

IKEY=variable

specifies a SAS variable that contains the CALC KEY. Owner records of a set can be predefined to have a CALC key. Using the CALC key enables direct access to the owner records. The IKEY option is used with the IKEYLEN and KEYOFF options.

IKEYLEN=variable

specifies a SAS variable that contains the length of the CALC key. The SAS variable for the IKEYLEN option is defined as a numeric variable.

KEYOFF=variable

specifies a numeric SAS variable that is set to the position of the CALC key within the CA-IDMS record.

LRECL=length

specifies the length of the SAS buffers that are used as I/O areas when CA-IDMS calls are executed. The length must be greater than or equal to the length of the longest record accessed. If LRECL= is not specified, the default buffer length is 1000 bytes. Note that the LRECL option on a statement overrides the LRECL system option. See CA-IDMS Input Buffer for more information.

RECORD=variable

specifies a SAS variable that contains the name of the CA-IDMS record type that you want to access. The record type must be included in the subschema that was specified in the INFILE statement.

SEQUENCE=variable

names a SAS variable that contains the requested record location within the set or area. This variable can also establish currency and/or determine the direction of the traversal. Valid values for the SEQUENCE SAS variable are:

NEXT
FIRST
LAST
PRIOR
nth
CURRENT
OWNER
DUP
USING

SET=variable

names a SAS variable that contains the name of the CA-IDMS set that you want to access. The set must be included in the subschema that was specified in the INFILE statement.

SORTFLD=variable

names a SAS variable that contains the sort control element to be used in searching the sorted set. If the FUNC= variable contains RETURN, SORTFLD= will contain the record's symbolic key, after successful completion of the call to CA-IDMS.

Standard INFILE Statement Options

The following standard INFILE statement options can be specified in a CA-IDMS INFILE statement:

OBS=n

specifies, in a CA-IDMS DATA step program, the maximum number of CA-IDMS function calls to execute. This number includes INPUT statements that do not retrieve data, such as BIND.

STOPOVER

stops processing if the record returned to the input buffer does not contain values for all the variables that are specified in the CA-IDMS INPUT statement.

OBS= and STOPOVER are the only standard INFILE options that can be specified in a CA-IDMS INFILE statement.

One other standard INFILE statement option, the MISSOVER option, is the default for CA-IDMS INFILE statements and does not have to be specified. The MISSOVER option prevents SAS from reading past the current record data in the input buffer if values for all variables specified by the CA-IDMS INPUT statement are not found. Variables for which data is not found are assigned missing values. Without the default action of the MISSOVER option, SAS would issue another function call any time the INPUT statement execution forced the input pointer past the end of the record.

See SAS Statements: Reference for complete descriptions of these options.

Summary of CA-IDMS INFILE Statement Options

The following table summarizes the CA-IDMS INFILE statement options.

Summary of CA-IDMS INFILE Statement Options
Option	Specifies
AREA=	the variable that contains the CA-IDMS area name.
DANAME=	the variable that contains database to be accessed by the run unit.
DANODE=	the variable that contains the central version of CA-IDMS where the database resides.
DBKEY=	the variable that contains a database record's key.
DCNAME=	the variable that contains the name of the CA-IDMS dictionary where the subschema is defined.
DCNODE=	the variable that contains the DC/UCF system needed to process the database requests.
ERRSTAT=	the variable to which the CA-IDMS error status is assigned after each CA-IDMS call.
FUNC=	the variable that contains the CA-IDMS call function used when a CA-IDMS INPUT statement is executed.
IKEY=	the variable that contains the value of the CALC KEY.
IKEYLEN=	the variable that contains the length of the CALC key.
KEYOFF=	the variable that is set to the position of the CALC key within the CA-IDMS record.
LRECL=	the length of the SAS buffers used as I/O areas when CA-IDMS calls are executed.
<MISSOVER>	that SAS does not read past the current record data in the input buffer if values for all variables specified by the CA-IDMS INPUT statement are not found. Specified by default.
OBS=	the maximum number of CA-IDMS function calls to be issued by the DATA step.
RECORD=	the variable that contains the name of the CA-IDMS record that you want to access.
SEQUENCE=	the variable that contains the requested record location within the set or area, establishes currency, and determines the direction of the traversal.
SET=	the variable that contains the name of the CA-IDMS set that you want to access.
SORTFLD=	the variable that contains the value of the sort-control element to be used in searching the sorted set.
STOPOVER	that SAS stops processing if the record returned to the input buffer does not contain values for all variables specified in the CA-IDMS INPUT statement.