SAS/ACCESS Interface to CA-IDMS Software: Reference

Overview of the DATA Step Statement Extensions

Special SAS System 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 the SAS System the parameters that are needed to build CA-IDMS calls. The CA-IDMS INFILE statement

names the subschema
names SAS variables to contain
- 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 chapter.

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 of 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 the SAS System 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 allows access to all of the DEPARTMENT records. This example uses the IDMS option in the INFILE statement, which tells the SAS System 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;

[1] The DATA statement references a temporary SAS data set called ORG_DEPARTMENT, which is opened for output.

[2] The INFILE statement tells the SAS System 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.

[3] 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.

[4] 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.

[5] 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 are 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 allows the DATA step to check the call status that is returned from CA-IDMS.

[6] 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.

[7] When this INPUT statement executes, data are moved from the input buffer into the program data vector.

[8] The ISEQ value is changed to NEXT to generate an OBTAIN NEXT DEPARTMENT RECORD IN AREA ORG-DEMO-REGION.

[9] For the subsequent interations of the DATA step, the RETURN statement causes execution to return to the beginning of the DATA step.

[10] For any unexpected status codes, a message is written to the SAS log and the DATA step stops.

[11] The PRINT procedure prints the contents of the WORK.ORG-DEPARTMENT data set.

SAS Log shows the SAS log for this example.

SAS Log

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.

Department List shows the output of this example.

Note: The log shows that 11 records were read from the infile, but Department List shows only 9 observations. Every time the SAS System 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]

Department List

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

Chapter Contents
Previous
Next
Top of Page

	The DATA statement references a temporary SAS data set called ORG_DEPARTMENT, which is opened for output.
	The INFILE statement tells the SAS System 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 are 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 allows 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 are 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 interations of the DATA step, the RETURN statement causes execution to return to the beginning of the DATA step.
[10]	For any unexpected status codes, a message is written to the SAS log and the DATA step stops.
[11]	The PRINT procedure prints the contents of the WORK.ORG-DEPARTMENT data set.