Implementing Security for IMS › Application Interface › Invoke the Application Interface

Invoke the Application Interface

To use the CA Top Secret IMS application interface, security must be properly installed. In an IMS TM environment, this means that message region security must be active. Message region security is controlled by the IMS parameter ISIS=.

In a DLIBATCH environment, security is controlled by the CA Top Secret DL1B control option; this option must be set to YES for the application interface to be properly secured.

If security is not properly installed, U0476 abends will occur when IMS attempts to process the application interface calls.

To invoke the CA Top Secret IMS application interface, the application program must issue a DL/I call specifying a special function code of TSS, and passing a request record that describes the processing to be performed by the application interface.

The request record is essentially a parameter list containing fields supplied by the application program and return areas which will be filled in by CA Top Secret upon return from the request. This record is supplied as the second parameter on the DL/I call.

Note: All fields in the request record should be initialized before the call is made.

In IMS, a partial list of resource classes that can be checked using the request record includes:

• ABSTRACT
• APPL
• DBD
• FIELD
• PSB
• TERMINAL
• UR1
• UR2

COBOL Example

1      78
000010 IDENTIFICATION DIVISION .
           .
001000 DATA DIVISION .
           .
001010*
001020*
001030* ENSURE TSSCPLC IS IN THE COBOL COPY LIBRARY OR COPY YOUR OWN
001040* VERSION INLINE INTO PROGRAM, USE OF COPY LIBRARY IS
001050* RECOMMENDED SO THAT CHANGES WILL ONLY REQUIRE RECOMPILE
001060* AND NOT RE‑CODING OF SOURCE
001070* COPYBOOK CAN BE FOUND IN THE OPTIONAL MATERIALS DATASET
001080 01    TSS                 PIC X(4) VALUE 'TSS '.
001090 01 TSSCPLC COPY TSSCPLC REPLACING ==:RTLN:==BY==256==.
           .
002000 PROCEDURE DIVISION .
           .
           .
010010*
010020*
010030* CALL CA Top Secret APPLICATION INTERFACE TO EXTRACT
010040* INSTALLATION DATA FROM USERS SECURITY RECORD
010050*
010060*
010065 MOVE 'TCPLV5L1' TO TSSHEAD
010070 MOVE 'DUFXTR' TO TSSCLASS.
010080 MOVE 'TSSAI'  TO TSSAI.
010090 CALL 'CBLTDLI' USING TSS , TSSCPL.
010100 IF  NOT TSSROK GO TO 100‑CHECK‑TOP‑RETURN.
010110 MOVE TSSRTN  TO USER‑AREA‑FOR‑INST‑DATA.
           .
020010*
20020*
020030* CANCEL CA Top Secret APPLICATION INTERFACE. DO THIS WHEN THE
020040* CA Top Secret INTERFACE IS NO LONGER REQUIRED BY PROGRAM AND
020050* THUS FREE UP THE STORAGE IT OCCUPIES IF NOT IN COMMON STORE
020060*
020070*
020090 MOVE 'TSSAI'  TO TSSAI.
020100 CANCEL TSSAI.

Assembler Example

COPY  TSSCPLA                 MAKES MACRO AVAILABLE
TSS        DC    CL4'TSS '               DLI CALL REQUEST
TSSCPL     #TSSCPLA TRLN=2048            APPLICATION INTERFACE REQUEST
           .
           .
           .
          CALL  ASMTDLI,(TSS,TSSCPL),VL CALL APPLICATION INTERFACE

PL/I Example

PLIEX1: PROC OPTIONS(MAIN);
           .
           .
           .
%INCLUDE(TSSCPLP);                         /* APPLIC INTRF PLIST  */
TSSRTNCTL=2048;
ALLOCATE TSSCPL;
                        /* APPLIC INTRF PLIST  */
DCL 1 TSS CHARACTER(04) INIT('TSS ');      /* INDICATE TSS REQ    */
DCL 1 PCOUNT STATIC FIXED BIN(31) INIT(2); /* CONT OF PARMS AFTER */
           .
           .
           .
          CALL PLITDLI (PCOUNT,TSS,TSSCPLP)