| SAS/ACCESS Interface to CA-IDMS: Reference |
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 box that appears below 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. ![[cautend]](../common/images/cautend.gif)
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 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 will be used in the function call, which will
produce unexpected results.
To generate the ACCEPT CURRENCY <record-name|set|area> INTO DBKEY function call, specify
these options:
And one of these
options:
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;
.
.
.
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;
.
.
.
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.
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 the DATA
step will access before any data are retrieved. The BIND RECORD function
call does not retrieve any data from CA-IDMS. A BIND function call is not
necessary if no data are being retrieved, i.e., you are issuing a FIND, ACCEPT,
or RETURN function call.
To generate the BIND RECORD function call, specify these
options:
The
following code 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;
.
.
.
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
they will be discussed together. There are six formats of the FIND and OBTAIN
functions. Each one will be described individually.
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 with No Arguments.
To generate the FIND|OBTAIN CALC
record-name
function call, specify these options:
To generate the FIND|OBTAIN CALC DUP
record-name function call, include:
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]]( ../common/images/sym01.gif) |
FUNCT is assigned the value of FIND. |
![[2]]( ../common/images/sym02.gif) |
RECNAME is assigned the name of the record that you want to access. In this
example, the record is the EMPLOYEE record. |
![[3]]( ../common/images/sym03.gif) |
CKEY is assigned the character value of '0101', which is the value of the
CALC key of the EMPLOYEE record 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]]( ../common/images/sym04.gif) |
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]]( ../common/images/sym05.gif) |
KLEN is set to 4, which is the length of the CALC key, the employee ID. |
![[6]]( ../common/images/sym06.gif) |
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]]( ../common/images/sym07.gif) |
FUNCT is set to OBTAIN to generate an OBTAIN CALC function call to CA-IDMS. |
![[8]]( ../common/images/sym08.gif) |
SEQ is set to DUP so the code will generate 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]]( ../common/images/sym09.gif) |
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. |
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:
And optionally use one of the following:
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;
.
.
.
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:
And optionally:
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;
.
.
.
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 or not the set has been assigned owner pointers.
To generate the FIND|OBTAIN OWNER function call, specify
these options:
The following example shows an OBTAIN OWNER function
call. This example assumes 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;
.
.
.
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 will be 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, currency 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:
To generate the FIND|OBTAIN
record WITHIN set|record CURRENT USING sortfield function
call, include:
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. ;
.
.
.
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:
Follow these rules when selecting records within
an area:
To generate the FIND | OBTAIN NEXT | PRIOR | FIRST | LAST
| nth <record> WITHIN set|area function call, specify:
And one of these options:
And optionally:
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. ;
.
.
.
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:
And optionally:
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;
.
.
.
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;
.
.
.
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:
To issue the DML IF statement, specify these
options:
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;
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:
To generate the RETURN CURRENCY <set>
NEXT |PRIOR|FIRST|LAST INTO DBKEY key INTO SORTKEY skey function call, specify these options:
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;
.
.
.
To generate the RETURN USING SORTKEY <set>
INTO DBKEY key INTO SORTKEY skey function call,
specify these options:
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;
.
.
.
Options Needed to Generate Function Calls for COBOL DML
outlines the SAS INFILE parameters that are required to generate each of the
CA-IDMS function calls for COBOL DML.
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 if 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 if 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 if 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.
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 (MVS 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 you want to return to an earlier input source, it is not
necessary to repeat all options specified in the original INFILE statement.
The SAS System 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
the SAS System.
Copyright © 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.
