Specifying DML Function Calls

Options for CA-IDMS Function Calls

The following sections describe which options to use to issue each of the CA-IDMS function calls: ACCEPT, BIND, FIND, OBTAIN, GET, IF, and RETURN.
Each of the following sections shows the required and optional information that needs to be specified in INFILE statement option variables. The INFILE statement option variables are SAS variables assigned in the INFILE statement.
For example, to generate the ACCEPT CURRENCY function call, you must first assign INFILE statement option variables by using FUNC=, RECORD=, and SEQUENCE=. Then you can give the variables the values ACCEPT, DEPARTMENT, and CURRENT, respectively. See the example below for a detailed description of the ACCEPT CURRENCY function call.
Note: The values of INFILE statement option variables remain set and are used for each subsequent function call unless you override or reassign their values.

ACCEPT Function Call

The ACCEPT db-key statement moves the db-key of the current record to the DBKEY= option variable that you have defined in the CA-IDMS INFILE statement. After accepting the db-key, you can use the FIND or OBTAIN db-key statements to access records directly by using the db-key that you saved from the ACCEPT db-key function call.
The db-key is a unique 4-byte identifier assigned to a record when the record is stored in the database. The db-key remains unchanged until the record is erased or the database is unloaded and reloaded. Any record in the subschema can be accessed directly using its db-key, regardless of its location.
Note: If other function calls to CA-IDMS are made before you want to use the db-key again, it must be copied into another variable. If the db-key is not needed for the next function call, it must be blanked out, or its value is used in the function call. This produces unexpected results.
To generate the ACCEPT CURRENCY <record-name | set | area> INTO DBKEY function call, specify these options:
  • FUNC= ACCEPT
  • DBKEY= contains the current record's DBKEY
  • SEQUENCE= CURRENT | NEXT | PRIOR | OWNER.
And specify one of these options:
  • RECORD= the IDMS record name
  • SET= the IDMS set name
  • AREA= the area the record participates in
The following example shows the ACCEPT CURRENCY function call for the DEPARTMENT record. The numbers in the program correspond to numbered comments following the program. 
  infile empss01 idms func=func1 record=rec1 
          dbkey=key1 errstat=err sequence=seq1;
   .
   .
   .
1 func1 = 'ACCEPT';
2 rec1  = 'DEPARTMENT';
3 seq1  = 'CURRENT';
   input;
   if err eq '0000' then do
4 put @1 'DBKEY OF RECORD = '  @19 key1;
   .
   .
   .
1 FUNC1 is assigned the value of ACCEPT.
2 REC1 is assigned the record name DEPARTMENT because you want the db-key of this record. Before you can issue an ACCEPT function call for a specific record, you must first establish currency on the record.
3 SEQ1 is set to CURRENT to indicate that you want the db-key of the DEPARTMENT record that is current of the run unit.
4 After successful execution of the ACCEPT function call, KEY1 contains the db-key for the current DEPARTMENT record. The PUT statement prints the value of KEY1 on the SAS log.
The following example shows the ACCEPT NEXT function call for the DEPT-EMPLOYEE set. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=func1 set=set1 
          dbkey=key1 errstat=err sequence=seq1;
   .
   .
   .
1 func1   = 'ACCEPT';
2 set1    = 'DEPT-EMPLOYEE';
3 seq1    = 'NEXT';
   input;
   if err eq '0000' then do
4 put @1 'DBKEY OF RECORD = '  @19 key1;
   .
   .
   .
1 FUNC1 is assigned the function of ACCEPT.
2 SET1 is assigned the set name that is current of the run unit. For example, if you have currency on the EMPLOYEE record, the ACCEPT NEXT causes the db-key of the next record in the DEPT-EMPLOYEE set to be returned from the function call to CA-IDMS. The next record in the DEPT-EMPLOYEE set could be either an EMPLOYEE record or a DEPARTMENT record, depending on your location in the set when the ACCEPT NEXT function call is issued.
3 SEQ1 is set to NEXT to indicate that you want the db-key from the next record in the DEPT-EMPLOYEE set.
4 After successful execution of the ACCEPT function call, KEY1 contains the db-key for the NEXT record. The PUT statement prints the db-key on the SAS log.
You can now save the db-key to use now or later with the OBTAIN or FIND functions. Using the db-key gives you direct access to the record regardless of established currencies.

BIND Function Call

The only form of the BIND function that is needed in the CA-IDMS DATA step is the BIND RECORD. The BIND RECORD statement establishes addressability for a CA-IDMS record so that its data can be retrieved and placed into the input buffer. A BIND RECORD must be issued for every record type that the DATA step accesses before any data is retrieved. The BIND RECORD function call does not retrieve any data from CA-IDMS. A BIND function call is not necessary if no data is being retrieved, that is, if you are issuing a FIND, ACCEPT, or RETURN function call.
To generate the BIND RECORD function call, specify these options:
  • FUNC= BIND
  • RECORD= the IDMS record name
The following example shows the BIND RECORD function call. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=func1 record=recname 
   .
   .
   .
1 func1    = 'BIND';
2 recname  = 'DEPARTMENT';
3 input;
   .
   .
   .
1 FUNC1 is assigned the function of BIND.
2 RECNAME is assigned the value of DEPARTMENT because this is the record on which you want to perform the BIND RECORD.
3 This INPUT statement generates and submits the BIND RECORD function call to CA-IDMS.

FIND and OBTAIN Function Calls

The FIND function locates a record in the database. The OBTAIN function locates a record and moves the data from the record to the input buffer. The FIND and OBTAIN functions have identical options so that they are discussed together. There are six formats of the FIND and OBTAIN functions. Each one is described individually.

FIND/OBTAIN CALC Function

The FIND/OBTAIN CALC function accesses a record by using its CALC key value. The record must be stored in the database with a location mode of CALC. The FIND/OBTAIN CALC DUP function accesses duplicate records with the same CALC key as the current record, provided that the current record of the same record type had been accessed using FIND/OBTAIN CALC.
For an example program that locates records directly using CALC key values that have been stored in a SAS data set, see Example: Using the Trailing @ and the INPUT Statement with No Arguments.
To generate the FIND | OBTAIN CALC record-name function call, specify these options:
  • FUNC= FIND or OBTAIN
  • RECORD= an IDMS record name
  • IKEY= a valid IDMS record CALC key
  • KEYOFF= the offset into the record where the CALC key is located
  • IKEYLEN= the length of the CALC key
To generate the FIND | OBTAIN CALC DUP record-name function call, include this option:
  • SEQUENCE = 'DUP'
The following example shows a FIND CALC function call for the EMPLOYEE record followed by an OBTAIN CALC DUP for the same record. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=funct record=recname 
          ikey=ckey keyoff=key0 errstat=stat 
          sequence=seq ikeylen=klen;
   .
   .
   .
1 funct      = 'FIND';
2 recname    = 'EMPLOYEE';
3 ckey       = '0101';
4 key0       = 0;
5 klen       = 4;
6 input;
   .
   .
   .
7 funct      = 'OBTAIN';
8 seq        = 'DUP';
   if stat eq '0000' then do
9 input @1   employee_id    4.0
         @5   firstname        $char10.
         @15  lastname         $char15.
         @30  street           $char20.
         @50  city             $char15.
         @65  state            $char2.
         @67  zip              $char9.
         @76  phone            10.0
         @86  status           $char2.
         @88  ssnumber         $char9.
         @97  startdate        6.0
         @103 termdate         6.0
         @109 birthdate        6.0;
   .
   .
   .
1 FUNCT is assigned the value of FIND.
2 RECNAME is assigned the name of the record that you want to access. In this example, the record is the EMPLOYEE record.
3 CKEY is assigned the character value of '0101', which is the value of the CALC key of the EMPLOYEE record that you want to access. Upon successful execution of the FIND CALC function call, currency is set to the EMPLOYEE record with the employee ID number of 0101. The CALC key for the employee record is the employee ID.
4 KEYO is set to zero because the employee ID or the CALC key is at offset zero in the employee record. In other words, the employee ID is the first element in the employee record.
5 KLEN is set to 4, which is the length of the CALC key, the employee ID.
6 This INPUT statement generates and submits the FIND CALC function call to CA-IDMS. No SAS variables are created. The FIND function establishes currency but does not retrieve data.
7 FUNCT is set to OBTAIN to generate an OBTAIN CALC function call to CA-IDMS.
8 SEQ is set to DUP so that the code generates an OBTAIN CALC DUP function call. RECNAME, CKEY, KLEN, and KEYO are still set from the previous FIND CALC function call and do not have to be set.
9 This INPUT statement contains SAS variables because the OBTAIN function call causes CA-IDMS to locate the specified record and move the data associated with the record to the record buffer.
The INPUT keyword submits the generated function call, which, if successful, returns a record to the buffer. The remaining portion of the INPUT statement maps fields from the buffer to the program data vector.

FIND/OBTAIN CURRENT Function

The FIND/OBTAIN CURRENT function accesses records by using established currencies. You can FIND or OBTAIN records that are current of the record type, set, or area. You can also use this form of the FIND or OBTAIN function call to establish the appropriate record as current of the run unit.
To generate the FIND | OBTAIN CURRENT OF <record | set | area> function call, specify these options:
  • FUNC= FIND or OBTAIN
  • SEQUENCE= CURRENT
And if needed, use one of the following options:
  • RECORD= an IDMS record name
  • SET= an IDMS set name
  • AREA= the area in which the record is a participant
The following example shows a FIND CURRENT function call for the DEPARTMENT record. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=funct record=recname 
          errstat=stat sequence=seq;
   .
   .
   .
1 funct      = 'FIND';
2 seq        = 'CURRENT';
3 recname    = 'DEPARTMENT';
4 input;
   .
   .
   .
1 FUNCT is assigned the value of FIND.
2 SEQ is assigned CURRENT so that the function call to CA-IDMS will locate the current record of the specified record type, set, or area. In this example, the code is looking for the current record of the record type DEPARTMENT.
3 RECNAME specifies the name of the record type that is to be accessed. In this example, the record is the DEPARTMENT record.
You can use the AREA option or the SET option instead of the RECORD option with the FIND/OBTAIN CURRENT function to locate the current record of the named area or set, respectively.
4 This INPUT statement generates and submits the FIND CURRENT function call to CA-IDMS.

FIND/OBTAIN DBKEY Function

The FIND/OBTAIN DBKEY function locates a record directly using a db-key that has been stored previously by your DATA step program. The ACCEPT function is used to acquire the record's db-key. Any record in the subschema can be accessed directly using the db-key, regardless of its location mode.
To generate the FIND | OBTAIN DBKEY function call, specify these options:
  • FUNC= FIND or OBTAIN
  • DBKEY= a db-key value
And specify the following option:
  • RECORD= the IDMS record name
The following example shows an ACCEPT NEXT function call, which acquires the db-key of a record. It is followed by an OBTAIN DBKEY function call, which uses the db-key acquired by the ACCEPT NEXT function call. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=funct dbkey=dkey 
          errstat=stat sequence=seq;
   .
   .
   .
1 funct      = 'ACCEPT';
   seq        = 'NEXT';
2 dkey       = '    ';
   input;
   .
   .
   .
   funct      = 'OBTAIN';
3 seq        = '       ';
4 input @1   department_id      4.0
         @5   department_name    $char45.
         @50  department_head    4.0;
   .
   .
   .
1 FUNCT is assigned the value of ACCEPT to get the db-key for the next record, based on currency.
2 DKEY is set to blanks to receive the new db-key.
After the ACCEPT function call has successfully executed, the db-key is returned to the DATA step in the DKEY variable. The db-key can be saved and used later to access the record directly.
3 The SEQ option is set to blanks because it is not used with the OBTAIN DBKEY function call.
If the RECORD option is used with FIND/OBTAIN DBKEY, the db-key value must contain a db-key of the named record type.
4 The INPUT statement generates and submits the OBTAIN DBKEY function call. If successful, data returned to the buffer is mapped to the named variables.

FIND/OBTAIN OWNER Function

The FIND/OBTAIN OWNER function locates the owner record of the current set. This function call can be used to return the owner record of any set, whether the set has been assigned owner pointers.
To generate the FIND | OBTAIN OWNER function call, specify these options:
  • FUNC= FIND or OBTAIN
  • SET= an IDMS set name
  • SEQUENCE= OWNER
The following example shows an OBTAIN OWNER function call. This example assumes that currency is on an employee record occurrence. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=funct set=inset 
          errstat=stat sequence=seq;
   .
   .
   .
1 funct      = 'OBTAIN';
2 seq        = 'OWNER';
3 inset      = 'DEPT-EMPLOYEE';
4 input @1   department_id      4.0
         @5   department_name    $char45.
         @50  department_head    4.0;
   .
   .
   .
1 FUNCT is assigned the value of OBTAIN so that the data for the owner record is returned to the DATA step program.
2 SEQ is assigned OWNER to generate an OBTAIN OWNER function call.
3 INSET specifies the set whose owner record is to be retrieved.
4 The INPUT statement generates and submits the OBTAIN OWNER function call. If successful, data returned to the buffer are mapped to the named variables.

FIND/OBTAIN SORT KEY Function

The FIND/OBTAIN SORT KEY function locates a member record in a sorted set. Sorted sets are ordered in ascending and descending sequence based on the sort field value. The search for member records begins with either the current record of the set or the owner of the set. The record that is retrieved is the first record that has a sort field value that is equal to the value in the SORTFLD SAS variable. If no record matches the SORTFLD value, currencies to the next and prior records of the set are maintained so that the DATA step program can traverse the set using the SORTFLD value to perform a generic search.
To generate the FIND | OBTAIN record WITHIN set | record USING sortfield function call, specify these options:
  • FUNC= FIND or OBTAIN
  • SORTFLD= a valid sort field value
  • RECORD= an IDMS record name
  • SET= an IDMS set name
To generate the FIND | OBTAIN record WITHIN set | record CURRENT USING sortfield function call, include the following option:
  • SEQUENCE= CURRENT
The following example shows an OBTAIN record WITHIN CURRENT set USING sortfield function call. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=funct record+recname
          errstat=stat sequence=seq set=inset 
          sortfld=skey;
   .
   .
   .
1 funct      = 'OBTAIN';
2 seq        = 'CURRENT';
3 skey       = 'GARFIELD' || 'JENNIFER';
4 recname    = 'EMPLOYEE';
5 inset      = 'EMP-NAME-NDX';
6 input @1   employee_id       4.0
         @5   firstname        $char10.
         @15  lastname         $char15.
         @30  street           $char20.
         @50  city             $char15.
         @65  state            $char2.
         @67  zip              $char9.
         @76  phone            10.0
         @86  status           $char2.
         @88  ssnumber         $char9.
         @97  startdate        6.0
         @103 termdate         6.0
         @109 birthdate        6.0
         @115 filler01         $char2. ;
   .
   .
   .
1 FUNCT is assigned the value of OBTAIN to retrieve the data for the employee record with the sort key of JENNIFER GARFIELD.
2 SEQ is set to CURRENT to indicate that the search begins with the current record of the set specified in INSET.
3 SKEY contains the value of the sort control element to be used in searching the sorted set. In this example, SKEY is set to the last and first name value of the employee name sort control element in the EMP-NAME-NDX set where you want to begin the search.
4 RECNAME is set to the name of the record to retrieve. In this example, you are looking for the EMPLOYEE record.
5 INSET is assigned the name of a sorted set
6 The INPUT statement generates and submits the OBTAIN SORTFLD WITHIN CURRENT set function call. If successful, data is mapped from the buffer to the named variables.

FIND/OBTAIN WITHIN SET or AREA Function

The FIND/OBTAIN WITHIN function locates a record either logically, based on set relationships, or physically, based on database location. Using various options with FIND/OBTAIN WITHIN, you can either access each record sequentially in a set or area, or select specific occurrences of a given record within a set or area.
Follow these rules when selecting members within a set::
  • Currency must be established on a set before attempting to access records in the set.
  • The next or prior records in the set are determined by the record that is current for the set named in the SET= option. The set must have prior pointers defined in order to retrieve records using the SEQUENCE= option of PRIOR.
  • The first or last record in a set is the first or last member in the logical order of the set. The last record in a set can be accessed only if prior pointers have been established for the set.
  • The nth record in a set is the set member in the nth position of the set. The search for the nth member begins with the owner of the current set and continues until the nth record is located or until an end-of-set condition occurs. If the nth number is negative, the search uses prior pointers. To use negative numbers, prior pointers must have been established for the set.
  • When an end-of-set occurs, the owner of the set becomes the current record of the run-unit, the record type, its area, and its set.
Follow these rules when selecting records within an area:
  • The first record within an area is the record with the lowest db-key. The last record within an area is the record with the highest db-key.
  • The next record within an area is the record with the next highest db-key in relationship to the record that is current of the named area. The prior record works the same way, except the prior record is the record with the next lowest db-key.
  • Before the next or prior record within an area can be requested, the first, last, or nth record within an area must be accessed to correctly establish a starting position within the area.
To generate the FIND | OBTAIN NEXT | PRIOR | FIRST | LAST | nth record> WITHIN set | area function call, specify this option:
  • FUNC= FIND or OBTAIN
And specify one of these options:
  • SET= an IDMS set name
  • AREA= the area that the record participates in
  • SEQUENCE= NEXT | PRIOR | FIRST | LAST | nth
If needed, specify this option:
  • RECORD= an IDMS record name
The following example shows an OBTAIN PRIOR record WITHIN AREA function call. Currency has already been established on an EMPLOYEE record. The numbers in the program correspond to the numbered comments following the program. 
  infile empss01 idms func=funct area=subarea record=recname errstat=stat 
          sequence=seq;
   .
   .
   .
1 funct      = 'OBTAIN';
2 seq        = 'PRIOR';
3 subarea    = 'EMP-DEMO-REGION';
   recname    = 'EMPLOYEE'
4 input @1   employee_id    4.0
         @5   firstname        $char10.
         @15  lastname         $char15.
         @30  street           $char20.
         @50  city             $char15.
         @65  state            $char2.
         @67  zip              $char9.
         @76  phone            10.0
         @86  status           $char2.
         @88  ssnumber         $char9.
         @97  startdate        6.0
         @103 termdate         6.0
         @109 birthdate        6.0
         @115 filler01         $char2. ;
   .
   .
   .
1 FUNCT is assigned the function of OBTAIN to retrieve the data for the EMPLOYEE record.
2 SEQ is set to PRIOR to indicate that the prior EMPLOYEE record is requested.
3 SUBAREA contains the name of the current area from which to retrieve the EMPLOYEE record.
4 The INPUT statement generates and submits the OBTAIN PRIOR function call. If successful, data is mapped from the buffer to the named variables.

GET Function Call

The GET statement moves the record that is current of the run unit into the input buffer. The GET function is used in conjunction with the FIND function. The FIND function locates records in the database without moving the data associated with the record to the record buffer.
To generate the GET <record-name> function call, specify the following option:
  • FUNC= GET
If needed, specify the following option:
  • RECORD= the IDMS record name
The following example shows the GET function call with no other options: 
  infile empss01 idms func=func1 record=rec1 
          errstat=err;
   .
   .
   .
1 func1      = 'GET';
2 input @1   department_id    4.0
         @5   department_name   $char45.
         @50  department_head   4.0;
   .
   .
   .
1 FUNC1 is assigned the value of GET.
2 The record that is current of the run unit is moved into the input buffer. Currency must be established before issuing the GET function.
The following example shows the GET function call for the DEPARTMENT record: 
  infile empss01 idms func=func1 record=rec1 
          errstat=err;
   .
   .
   .
   func1      = 'GET';
1 rec1       = 'DEPARTMENT';
   input @1   department_id      4.0
         @5   department_name    $char45.
         @50  department_head    4.0;
   .
   .
   .
1 The difference between this GET function call and the previous GET call is the use of the SAS variable REC1. This variable is set to the name of the specific record to move into the record buffer. In this example, the data associated with the DEPARTMENT record is moved. Currency must be established on the DEPARTMENT record before a GET call can be made for the record.

IF Function Call

The DML IF statement tests for the existence or membership of a record occurrence in a named set occurrence, and returns the result in the ERRSTAT variable.
There are two formats for the DML IF statement:
  • IF SET <NOT> EMPTY tests for the existence of a record occurrence and returns a status value of 0000 if the set occurrence is empty, and a status value of 1601 if the set occurrence is not empty.
  • IF <NOT> SET MEMBER checks the membership of the current record occurrence and returns a status value of 0000 if the record occurrence is a member of the named set occurrence, and a status value of 1608 if the record occurrence is a non-member.
To issue the DML IF statement, specify these options:
  • FUNC= IF
  • INSET= an IDMS set name
  • SEQUENCE= EMPTY | NEMPTY | MEMBER | NMEMBER
The following is an example of a DML IF function call: 
   
 infile empss01 idms func=funct record=recname 
          area=subarea errstat=stat sequence=seq 
          set=inset;

  1 funct   = 'FIND';
    seq     = 'FIRST';
    recname = 'DEPARTMENT';
    subarea = 'ORG-DEMO-REGION';
    input;
    if (stat ^= '0000') then go to staterr;

  2 funct   = 'IF';
  3 seq     = 'NEMPTY';
  4 inset   = 'DEPT-EMPLOYEE';
    recname = '                ';
    subarea = '                ';
    input;

  5 if (stat = '1601') then do;
    put @1 'Set ' @5 inset @14 'is not empty';
    stat    = '0000';
    _error_ = 0;
    end;
  6 else if (stat = '0000') then
    put @1 'Set' @5 inset @14 'is empty';
    else go to staterr;
    stop;
1 Run-unit currency for the DML IF statement is established by the previous function call. A FIND function call establishes run-unit currency on the record DEPARTMENT for the DML IF statement, but does not retrieve the record.
2 FUNCT is assigned the value of IF to indicate that a test is performed. Set currency is determined by the owner of the current record in the set named in INSET.
3 SEQ is set to NEMPTY to indicate the type of test.
4 INSET names the set to test.
5 The first SAS IF statement directs the DATA step to write a message to the log if the value of STAT is 1601, which means that the set is not empty.
6 The second SAS IF statement directs the DATA step to stop if the value of STAT is 0000, which means the set is empty.

RETURN Function Call

The RETURN function retrieves the db-key and the symbolic key for an indexed record without retrieving the record's data. This function establishes currency on the index set.
There are two formats for the RETURN function:
  • The RETURN CURRENCY function retrieves the db-key and symbolic key for an index entry based on established currencies or its position in the index set.
  • The RETURN USING SORTKEY function retrieves the db-key and symbolic key associated with a specific index key entry.
To generate the RETURN CURRENCY <set> NEXT | PRIOR | FIRST | LAST INTO DBKEY key INTO SORTKEY skey function call, specify these options:
  • FUNC= RETURN.
  • SET= an IDMS index set name.
  • SEQUENCE= FIRST | LAST | NEXT | PRIOR.
  • SORTFLD= upon successful completion of the function call, this SAS variable contains the current record's symbolic key.
  • DBKEY= upon successful completion of the function call, this SAS variable contains the current record's db-key.
The following example shows the RETURN FIRST function call:. 
  infile empss01 idms func=func1 errstat=err
          sequence=seq set=inset sortkey=skey dbkey=dkey;
    
   .
   .
1 func1      = 'RETURN';
2 seq        = 'FIRST';
3 inset      = 'EMP-NAME-NDX';
   input;
4 put @1 'DBKEY OF RECORD = '  @19 dkey;
   put @1 'SKEY OF RECORD = '  @19 skey;
   .
   .
   .
1 FUNC1 is assigned the function of RETURN.
2 SEQ is assigned the value of FIRST. FIRST returns the db-key for the first index entry in the set EMP-NAME-NDX. You could also request the db-key from the PRIOR, NEXT, or LAST index entry in the set by assigning these values to the SEQUENCE= option.
3 SET is assigned the name of the index set (INSET) from which the specified db-key is to be returned.
4 DKEY contains the db-key for the first entry in EMP-NAME-NDX. SKEY contains the symbolic key for the entry. The PUT statements print the db-key and the symbolic key on the SAS log.
To generate the RETURN USING SORTKEY <set> INTO DBKEY key INTO SORTKEY skey function call, specify these options:
  • FUNC= RETURN.
  • SEQUENCE= USING.
  • SET= an IDMS set name.
  • SORTKEY= the index key entry to search for. After successful completion of the function call, this SAS variable will contain the record's symbolic key.
  • DBKEY= upon successful completion of the function call, this SAS variable contains the record's db-key.
The following example shows the RETURN USING function call: 
   infile empss01 idms func=func1 record=recname 
          ikeylen=keyl errstat=err sequence=seq
          set=inset dbkey=dkey sortkey=skey;
   .
   .
   .
 1 func1      = 'RETURN';
 2 seq        = 'USING';
 3 inset      = 'EMP-NAME-NDX';
 4 skey       = 'GARFIELD  JENNIFER';
 5 keyl       =  25; 
 6 dkey       =  '  ';
   input;
   .
   .
   .
1 FUNC1 is assigned the function of RETURN.
2 SEQ is set to USING to indicate that the index key entry in SKEY is used to locate the db-key. In this example, SKEY is set to the last name and first name GARFIELD JENNIFER. The call returns the db-key and symbolic key of the first record that it encounters that contains the name GARFIELD JENNIFER.
3 INSET is the name of the index set to be searched.
4 SKEY specifies the index key value to search for.
5 KEYL specifies the length of index key value.
6 DKEY is set to blanks to receive the db-key.
After the RETURN function call has successfully executed, the db-key is returned to the DATA step in the DKEY variable.

Summary of Options Needed to Generate CA-IDMS Function Calls

The following table outlines the SAS INFILE parameters that are required to generate each of the CA-IDMS function calls for COBOL DML.
Options Needed to Generate CA-IDMS Function Calls for COBOL DML
COBOL DML Call1
INFILE Statement Options
ACCEPT db-key FROM CURRENCY
FUNC=ACCEPT
SEQUENCE=CURRENT
DBKEY=Required
ACCEPT db-key FROM record-name CURRENCY
FUNC=ACCEPT
SEQUENCE=CURRENT
RECORD=Required
DBKEY=Required
ACCEPT db-key FROM set-name CURRENCY
FUNC=ACCEPT
SEQUENCE=CURRENT
SET=Required
DBKEY=Required
ACCEPT db-key FROM area-name CURRENCY
FUNC=ACCEPT
SEQUENCE=CURRENT
AREA=Required
DBKEY=Required
ACCEPT db-key FROM set-name NEXT | PRIOR | OWNER CURRENCY
FUNC=ACCEPT
SEQUENCE=NEXT | PRIOR | OWNER
SET=Required
DBKEY=Required
BIND record-name
SEQUENCE=BIND
SET=Required
FIND/OBTAIN CALC* record-name
FUNC=FIND | OBTAIN
RECORD=Required
IKEY=Required
IKEYLEN=Required
FIND/OBTAIN DUPLICATE* record-name
FUNC=FIND | OBTAIN
SEQUENCE=DUP
RECORD=Required
IKEY=Required
IKEYLEN=Required
FIND/OBTAIN CURRENT
FUNC=FIND | OBTAIN
SEQUENCE=CURRENT
FIND/OBTAIN CURRENT record-name
FUNC=FIND | OBTAIN
SEQUENCE=CURRENT
RECORD=Required
FIND/OBTAIN CURRENT | NEXT | PRIOR | FIRST | LAST | Nth WITHIN set-name
FUNC=FIND | OBTAIN
SEQUENCE=NEXT | PRIOR | FIRST | LAST | Nth
RECORD=Optional
SET=Required
FIND/OBTAIN CURRENT | NEXT | PRIOR | FIRST | LAST | Nth WITHIN area-name
FUNC=FIND | OBTAIN
SEQUENCE=NEXT | PRIOR | FIRST | LAST | Nth
RECORD=Optional
AREA=Required
FIND/OBTAIN OWNER WITHIN set-name
FUNC=FIND | OBTAIN
SEQUENCE=OWNER
SET=Required
FIND/OBTAIN record-name WITHIN set-name USING sort-key
FUNC=FIND | OBTAIN
RECORD=Required
SET=Required
FIND/OBTAIN record-name WITHIN set-name CURRENT USING sort-key
FUNC=FIND | OBTAIN
SEQUENCE=CURRENT
RECORD=Required
SET=Required
FIND/OBTAIN DBKEY db-key
FUNC=FIND | OBTAIN
DBKEY=Required
FIND/OBTAINrecord-name DB-KEY IS db-key
FUNC=FIND | OBTAIN
RECORD=Required
DBKEY=Required
GET record-name
SEQUENCE=GET
SET=Required
RETURN db-key FROM index-set-name CURRENT | FIRST | LAST | NEXT | PRIOR KEY INTO symbolic-key
FUNC=RETURN
SEQUENCE=CURRENT | FIRST | LAST | NEXT | PRIOR
SET=Required
DBKEY=Required
SORTFLD=Required
RETURN db-key FROM index-set-name USING index-key-value KEY INTO symbolic-key
FUNC=RETURN
SEQUENCE=USING
SET=Required
DBKEY=Required
SORTFLD=Required
1KEYOFF= INFILE statement option required for these calls

How the CA-IDMS Function Call Is Generated

To determine which type of DML function call you want to generate, the CA-IDMS DATA step access method must make some assumptions from the various options that you specify. The access method first determines what value is specified in the FUNC option.
  • If the FUNC option contains BIND, GET, ACCEPT, or RETURN, the required options are checked for a value, then the optional options are checked, and the appropriate function call is generated.
  • If the FUNC option contains FIND or OBTAIN, the access method checks whether a value was entered for the following options:
    SORTFLD
    If the SORTFLD option was entered, the required and optional options for the OBTAIN or FIND with the SORTFLD are verified before a function call is generated. If the SORTFLD option was not entered, the access method then determines whether the IKEY option was entered to generate a function call using the CALC key.
    IKEY
    If the IKEY option was entered, then all of the required and optional options are verified for a function call using the CALC key. If the IKEY option was not entered, the access method then looks to see whether the DBKEY option was entered.
    DBKEY
    If the DBKEY was entered, the same verification is done for the options as before and a function call is generated. If DBKEY was not entered, then the access method looks to see whether the SEQUENCE option was entered.
    SEQUENCE
    If a value was entered for the SEQUENCE option, the value is examined. If the value is
    CURRENT
    The other options are checked to determine what type of currency call to generate.
    OWNER
    An OBTAIN or FIND OWNER or a FIND DUP OWNER function call is generated.
    NEXT, PRIOR, FIRST, LAST, or nth
    The access method tries to generate an OBTAIN or FIND WITHIN function call by using the other options that were entered.
If the access method cannot generate a function call from the options that you entered or if the options for a particular function call are incorrect, an error message is returned, the automatic variable _ERROR_ is set to 1, and the CA-IDMS call status is set to 9999. Your DATA step program should check for these conditions after each function call to the database.

Using Multiple Sources of Input

You can have more than one input source in a DATA step. For example, you can read from a CA-IDMS database and a SAS data set in the same DATA step. You cannot, however, read from more than one subschema in a single DATA step. If you want to use several external files (z/OS data sets) in a DATA step, use separate INFILE statements for each source.
The input source is set (or reset) when an INFILE statement is executed. The file or CA-IDMS subschema referenced in the most recently executed INFILE statement is the current input source for INPUT statements. The current input source does not change until a different INFILE statement executes, regardless of the number of INPUT statements executed.
If after you change input sources by executing multiple INFILE statements that you want to return to an earlier input source, it is not necessary to repeat all options specified in the original INFILE statement. SAS remembers options from the first INFILE statement with the same fileref or subschema name. In a standard INFILE statement, you need only specify the fileref. In a CA-IDMS INFILE statement, specify the subschema and IDMS. Options specified in a previous INFILE statement with the same fileref or subschema name cannot be altered.
Note: The subschema name cannot be the same name as a fileref on a JCL DD statement, a TSO ALLOC statement, or a filename's fileref for the current execution of SAS.
Copyright © SAS Institute Inc. All rights reserved.