Using the SAS/ACCESS Interface to CA-IDMS

Overview of the DATA Step Statement Extensions

Introduction to the CA-IDMS INFILE and CA-IDMS INPUT Statements

Special SAS extensions to the standard SAS INFILE statement enable you to access CA-IDMS data in a SAS DATA step. The extended statement is referred to as the CA-IDMS INFILE statement and its corresponding INPUT statement is referred to as the CA-IDMS INPUT statement. The CA-IDMS INFILE and CA-IDMS INPUT statements work together to generate and issue calls to CA-IDMS. A CA-IDMS DATA step can contain standard SAS statements as well as the SAS statements that are used with the SAS/ACCESS interface to CA-IDMS.

The CA-IDMS INFILE statement defines to SAS the parameters that are needed to build CA-IDMS calls. The CA-IDMS INFILE statement performs the following tasks:

names the subschema
names SAS variables to contain the following information:
- the dictionary name
- the database name
- the node name (for distributed DBMS)
- CA-IDMS functions (for example, OBTAIN or FIND)
- the area name
- the set name
- the record name
- the sort field
- the database key
- the CALC key
- the key offset
- the key length
- the status returned by the call

When it is executed, the CA-IDMS INPUT statement formats and issues the CA-IDMS function call using the parameters specified in the CA-IDMS INFILE statement.

The CA-IDMS INFILE statement is required in any DATA step that accesses a CA-IDMS database because the special extensions of the CA-IDMS INFILE statement specify the variables that set up the CA-IDMS calls. When a CA-IDMS INFILE statement is used with a CA-IDMS INPUT statement, the database function calls are issued.

The syntax and usage of the CA-IDMS INFILE and INPUT statements are described in detail later in this section.

CA-IDMS Record Currency

You need to understand the concept of currency before using the DATA step interface to CA-IDMS. CA-IDMS keeps track of the most recently accessed record by its database location or db-key. As each record is accessed, it becomes current for the run-unit, record type, set, or area. Some DML calls require that certain currencies are established before the call is issued. See your CA-IDMS documentation for more information about currency.

CA-IDMS Input Buffer

A buffer is allocated by SAS as an input area for data retrieval. The length of this buffer is specified by the LRECL= option in the CA-IDMS INFILE statement. The input buffer is formatted by CA-IDMS in the same way an input area for any CA-IDMS program is formatted.

The data INFORMATS specified in the CA-IDMS INPUT statement must match the original data format. This information can be obtained from CA-IDMS Integrated Data Dictionary (IDD) or from a COBOL or Assembler copy library, source programs, a SAS macro library, or other documentation sources. Database Administrator (DBA) staff at your installation can help you find the segment data formats you need.

Introductory Example of a DATA Step Program

The following example is a simple DATA step program that reads record occurrences from a CA-IDMS database and creates a SAS data set. Next, the program processes the SAS data set with PROC PRINT.

The example accesses the EMPLOYEE database with the subschema EMPSS01. This subschema enables access to all of the DEPARTMENT records. This example uses the IDMS option in the INFILE statement, which tells SAS that this particular external file reference is for a CA-IDMS database.

The numbers in the program correspond to the numbered comments following the program.

1  data work.org_department; 
   retain iseq;
2  infile empss01 idms func=func1 record=recname 
      area=iarea sequence=iseq errstat=err 
      set=iset;

   /* BIND the DEPARTMENT record  */
3  if_n_ = 1 then do;
      func1   = 'BIND';
      recname  = 'DEPARTMENT';
4     input;
      if (err ne '0000') then go to staterr;
      iseq = 'FIRST';
   end;

   /* Now get the DEPARTMENT records by issuing    */
   /* OBTAIN for DEPT record and test for success  */

   func1     = 'OBTAIN';
   recname   = 'DEPARTMENT';
   iarea     = 'ORG-DEMO-REGION';
5     input @;
6  if (err ne '0000' and err ne '0307') then go to 
      staterr;
   if err eq '0307' then do;
      _error_ = 0;   
      /* No more DEPT records so STOP */
      stop;
   end;
7  input
      @1   department_id     4.0
      @5   department_name   $char45.
      @50  department_head   4.0;

8  iseq = 'NEXT';
9  return;
   staterr:
10  put @1 'WARNING: ' @10 func1 @17 
      'RETURNED ERR =' @37 err;
      atop;
   end;
   run;

11  proc print data=work.org_department;
   run;

	The DATA statement references a temporary SAS data set called ORG_DEPARTMENT, which is opened for output.
	The INFILE statement tells SAS to use the EMPSS01 subschema. The IDMS option tells SAS that EMPSS01 is a CA-IDMS subschema instead of a fileref. This statement also tells the CA-IDMS interface to use the named SAS variables as follows: FUNC1 to store the function type RECNAME to store the record name IAREA to store the area name ISEQ to store the function call sequence information ISET to store the set name The CA-IDMS INFILE statement also tells the interface to store the error status from the call in ERR.
	The first time through the DATA step, all CA-IDMS records that will be accessed must be bound to CA-IDMS. To bind the DEPARTMENT record type, the program sets FUNC1 to BIND and RECNAME to DEPARTMENT.
	The CA-IDMS INPUT statement uses the values in the SAS variables FUNC1 and RECNAME to generate the first call to CA-IDMS. In this example, the call generated is a BIND for the DEPARTMENT record. All records must be bound to CA-IDMS before any data retrieval calls are performed. A null INPUT statement is used because the BIND function does not retrieve any CA-IDMS data.
	This INPUT statement also uses the values in the SAS variables FUNC1 and RECNAME, along with the values in ISEQ and IAREA to generate an OBTAIN FIRST DEPARTMENT RECORD IN AREA ORG-DEMO-REGION call. However, no data is moved into the program data vector because no variables are defined in the INPUT @; statement. The call holds the contents of the input buffer and enables the DATA step to check the call status that is returned from CA-IDMS.
	The program examines the status code returned by CA-IDMS. If CA-IDMS returns 0000, then the program proceeds to the next INPUT statement. If CA-IDMS does not return 0000 or 0307, then the program branches to the error routine.
	When this INPUT statement executes, data is moved from the input buffer into the program data vector.
	The ISEQ value is changed to NEXT to generate an OBTAIN NEXT DEPARTMENT RECORD IN AREA ORG-DEMO-REGION.
	For the subsequent iterations of the DATA step, the RETURN statement causes execution to return to the beginning of the DATA step.
	For any unexpected status codes, a message is written to the SAS log and the DATA step stops.
	The PRINT procedure prints the contents of the WORK.ORG-DEPARTMENT data set.

The following output shows the SAS log for this example.

SAS Log for Introductory DATA Step Program

   1           data work.org_department;
   2           infile empss01 idms func=func1 record=recname area=iarea
   3              sequence=iseq errstat=err set=iset;
   4
   5           err = '0000';
               .
               .
               .
   37          end;
   38          run;
   
   NOTE: The infile EMPSS01 is:
         Subschema=EMPSS01
   NOTE: 11 records were read from the infile EMPSS01.
         The minimum record length was 0.
         The maximum record length was 56.
   NOTE: The data set WORK.ORG_DEPARTMENT has 9 observations and 3 variables.
   NOTE: The DATA statement used 0.22 CPU seconds and 2629K.
   39          proc print data=work.org_department;
   40          run;
   
   NOTE: The PROCEDURE PRINT printed page 1.

The following output shows the results of this example.

Note: The log shows that 11 records were read from the infile, but the following results show only 9 observations. Every time SAS encounters a CA-IDMS INPUT statement that submits a call, it increments by one an internal counter that keeps track of how many record occurrences are read from the database. The count is printed to the SAS log as a NOTE. Because this program contains CA-IDMS INPUT statements that do not retrieve data, this count can be misleading. [cautionend]

Results of Introductory DATA Step Program

                     The SAS System      
 Obs    department_id   department_name            department_
                                                       head
  1      2000           ACCOUNTING AND PAYROLL          11
  2      3200           COMPUTER OPERATIONS              4
  3      5300           BLUE SKIES                     321
  4      5100           BRAINSTORMING                   15
  5      1000           PERSONNEL                       13
  6      4000           PUBLIC RELATIONS                 7
  7      5200           THERMOREGULATION               349
  8      3100           INTERNAL SOFTWARE                3
  9       100           EXECUTIVE ADMINISTRATION        30

Top of Page