Calling File-AID/Data Solutions with the API

The File-AID/Data Solutions API (Application Programming Interface) provides access to File-AID/Data Solutions from existing programs that will utilize any of the File-AID/Data Solutions functionality like Encryption and Euro Conversion.

Important

The File-AID Installer is required for these tasks.

Tasks

Perform the following tasks to provide a Callable Interface to File-AID/Data Solutions API (Applications Programming Interface) from your existing programs.

Task 4.1 Copy the Sample Call Program

The sample data set (hlq.SXVJSAMP) of File-AID/Data Solutions includes members that begin with CBL*****. These members are sample programs and required parameter layouts that demonstrate how the call works.

CBLCALL1 is a sample program that performs the call using the DD01SC (criteria data set) allocated in the JCL. You build the change criteria with the File-AID/Data Solutions on-line interface and save it in a file that DD01SC points to.

Task 4.2 Set the CBL1OPTS Parameter

Set the CBL1OPTS parameter which is used to change the installed default options in File-AID/Data Solutions. There should be no reason to change these options unless you wish to override the currently installed options. For more information, see Modify Batch Options at Execution.

Task 4.3 Set the CBL2CNTL Parameter

Set the CBL2CNTL parameter which provides Data Solutions with the source location and size of the data to be modified. The parameter instructs File-AID/Data Solutions to begin or end the modification process. It also provides Data Solutions with the number of requested functions that are to be initiated against the data. The maximum number of bytes (not digits) that can be passed to Data Solutions in the :X:-LENGTH-OF-DATA field is 32,760 bytes. For example, packed 7 digits would be 4 bytes.

Important

You must set :X:-MAXIMUM-DATA-LENGTH in the COBOL program to the largest number of bytes passed to Data Solutions during the job step.

If you created a call program prior to Data Solutions Release 10.1, and you receive the message INVALID API MAXIMUM DATA LENGTH, CANNOT BE < DATA LENGTH, then you need to update, recompile, and relink the CBLCALL1 program.

Task 4.4 Set the CBL3MSGS Parameter

Set the CBL3MSGS parameter which contains the return code from the File-AID/Data Solutions process, the number of messages received as a result of the call execution of File-AID/Data Solutions, and the maximum number of messages that can be passed to the calling program from File-AID/Data Solutions. Set the maximum number of messages that can be received by the calling program. File-AID/Data Solutions will pass the error messages along with the data. The calling program will decide how to handle the errors. The severity of the error will determine if the data is changed. The execution of an illogical instruction will cause File-AID/Data Solutions to abend.

Task 4.5 Ensure Program Has Copy Statements for Parameters

Ensure your program has copy statements for the parameters you changed.

CBL1OPTS, CBL2CNTL and CBL3MSGS are the layouts for the first three parameters needed in the sample program.

The sequence of the passed parameters is important. Use the sample program as a guide.

Task 4.6 Compile Your Program for Calls to Data Solutions with the API

Compile your program that calls File-AID/Data Solutions with the API.

Task 4.7 Set up COBOL API JCL for Data Privacy (DPR)

When you want to use your COBOL program with File-AID/Data Solutions’ Data Privacy option (File-AID/Data Solutions Primary Option D, Data Privacy - Dynamic Privacy Rules), use the online File-AID/Data Solutions to prepare sample JCL that you can then modify for use with your COBOL program.

Start a File-AID/Data Solutions mainframe online session.
File-AID/Data Solutions Primary Option Menu
         BMC AMI DevX File-AID/Data Solutions V23.1 Primary Option Menu
OPTION ===> D

   0 Parameters     - Data Solutions Parameters             USERID   - USERID9
   1 Date Aging     - Date Aging Solutions                  DATE     - 23/01/17
   2 Euro Tools     - Currency Conversions                  TIME     - 09:28
   3 Data Analyzer - Analysis Solutions                    TERMINAL - 3278
   4 Translator     - Data Translator                       CCSID    - 00037
   5 Generation     - Data Generation Solutions
   6 Field Exits    - Formatted Field Exits
   7 Encryption     - Data Encryption
   8 Replace        - Data Replace
   D Data Privacy   - Dynamic Privacy Rules
   U Utilities      - Print and File Override Utilities
   S Criteria Sets - Create or modify Criteria sets
   R XREF           - Create or change record layout cross reference
   T Tutorial       - Display information about Data Solutions
   X Exit           - Terminate Data Solutions and return to ISPF

      Use END to terminate File-AID

                   (c) Copyright 1997-2023 BMC Software, Inc.
Enter D to select Option D, Data Privacy.
Input Dataset Specification Screen
Enter Input Dataset Information, Record Layout and XREF Information, and Dynamic Privacy Rule Information.
Privacy Project List Screen
Enter S to select and confirm the Privacy Project you entered in the previous screen.Output Specification Screen
Type A for ANALYZE Option
Type N for Create audit trail.
Press Enter to continue to JCL Specification.
JCL Specification Screen
Enter JCL and JOB Statement Information to edit the generated JCL.Generated JCL Edit Screen
EDIT       SYS11073.T094728.RA000.USERID1.R0144732         Columns 00001 00072
Command ===>                                                  Scroll ===> CSR
****** ***************************** Top of Data ******************************
==MSG> -Warning- The UNDO command is not available until you change
==MSG>           your edit profile using the command RECOVERY ON.
000001 //USERID1A JOB (ACCOUNT),NAME,REGION=0M
000002 //* YOU ARE VIEWING JCL THAT FILE-AID/DATA SOLUTIONS 23.1 HAS GENERATED
000003 //* TO UPDATE DATASETS GLOBALLY.
000004 //*
000005 //* YOU CAN CHANGE THIS JCL IF DESIRED AND USE THE SUBMIT PRIMARY
000006 //* COMMAND TO SUBMIT THE JOB. THE CREATE OR REPLACE PRIMARY COMMAND
000007 //* CAN BE USED TO KEEP THIS JOBSTREAM FOR FUTURE USE.
000008 //*
000009 //* USE THE END COMMAND TO EXIT WITHOUT SUBMITTING THE JOB.
000010 //*
000011 //DASTEP   EXEC PGM=UDASOLUT,REGION=0M,
000012 //    PARM='SYSIN=DPRINPUT'
000013 //STEPLIB DD DISP=SHR,DSN=hlq.CXVJLOAD
000013 //         DD DISP=SHR,DSN=hlq.SXVJLOAD
000014 //XVJPRINT DD SYSOUT=*
000015 //DPRERROR DD SYSOUT=*
000016 //SYSLIST DD SYSOUT=*
000017 //DD01     DD DSN=USERID1.DASAMP.INVFILE,
000018 //             DISP=OLD
000019 //DD01RL   DD DSN=USERID1.DASAMP.LAYOUTS,
000020 //             DISP=SHR
000021 //FARULES DD *
000022 File-AID Rules
000023 8a8499e63c1e3c31013cac26a4ee003c Train
000024 //DPRINPUT DD *
000025 $$DD01 ANALYZE LAYOUT=INVFILE,CCSID=00037
000026 /*
000027 //
****** **************************** Bottom of Data ****************************
Modify the JCL:
1. Change the //DASTEP EXEC statement to execute your COBOL program.
2. Add any required STEPLIB data sets.
3. Replace the DD01 DD statement with any DD statements your program requires.
4. Remove the DPRINPUT DD statement and control card.
5. Save and/or submit your job.