This topic provides an overview of how to use BS2000 on your AE system. It describes how you download, transport, and extract BS2000 files to your system. The BS2000 agent, which supports all file transfer functions, allows you to set specific attributes and you can use remote function calls. Examples show how you run BS2000 commands through Script objects.
This topic includes the following:
- Program BS2-TAR and BS2000 Text Archive (TAR file)
- BS2000 Agent - File Transfer Support
- Service Program for Remote Function Call (RFC) Tasks
- Example BS2000 Commands
Program BS2-TAR and BS2000 Text Archive (TAR file)
The Automic Download Center provides BS2000 agent and BS2000 CallAPI files for download as a BS2000 text archive (TAR file). This text archive is a collection of BS2000 files that may include various file types such as SAM, ISAM, PAM, and PLAM. You use this text archive to transport the provided BS2000 files to your system. The program BS2-TAR then serves to extract them.
Download and Extract the Program BS2-TAR
BS2-TAR is available in IMAGE:TOOLS\BS2_TAR. This program extracts the text archive to your own user ID and is required for all transfers that are made with text archives. You do not require a license for it.
Two options are available for using BS2-TAR:
- BS2-TAR.BIN
This file contains the program BS2-TAR. This program has been transferred to the image folder using FTP in binary mode and you can re-transfer it to BS2000 using FTP as follows:
FTP
OPENBS2000 computer
user id (TSOS)
password
account
BIN
PUT BS2-TAR.BIN
BYE
In BS2000:
/CAT BS2-TAR.BIN,BS2-TAR,STATE=U,SHARE=YES,ACCESS=READ
- BS2-TAR.TAR
This file includes the latest version of the program BS2-TAR in TAR format. To use it, BS2-TAR must already be installed on the BS2000 computer.
The file is transferred to BS2000 in text mode using any file transfer and extracted in BS2000 with BS2-TAR as follows:
/FILE
BS2-TAR.TAR,LINK=TAR
/EXEC BS2-TAR
Use the Program BS2-TAR
The supplied TAR files whose names include NK4 are for NK4 pubsets. You can extract a TAR file with the following commands:
/FILE from
file, LINK=TAR
/EXEC BS2-TAR
The BS2000 agent supports all file transfer functions such as the transfers of text and binary files or file transfers with wildcard characters.
File Attributes for the File Transfer Destination
When defining a File Transfer object, you can specify file attributes for the destination in the File Transfer page. You can use all file attributes that comply with the file command. Enter them in the File Attributes field in the Destination Settings section. If you specify several file attributes, you need to separate them with commas. The following attributes are used by default:
- Text mode
- Binary mode
FCB=SAM,LINK=UCEXSAM,SPACE=(300,300)
SPACE=(300,300),BLKSIZE=STD,BLKCTRL=NO,FCB=PAM
Explicitly specified attributes replace default values or are added to the above command.
Important! You can use a file transfer to create ISAM files.
Example:
FCB=ISAM,BLKCTRL=DATA,RECFORM=V,KEYPOS=5,KEYLEN=8
Library Elements As Source and Destination
Elements of LMS libraries (PLAM) can be the source and the destination of a file transfer.
- Library elements can be transferred between two LMS libraries.
- A library element can be transferred to any destination system as a file.
- Text files from any destination system can be transferred to an LMS library.
Use the following format to specify the element:
*LIB(Library,Element(Version),Type)
The element version is optional. If you do not define a version, the source file reads the highest version, or the target file writes version @.
Examples:
*LIB($RS.LMS.LIB,MY.ELEMENT,S)
*LIB($RS.LMS.LIB,MY.*,S)
Keeping the Original Attributes
To use the attributes of source files for the destination files, use the option Keep Original File Attributes in the Destination Settings of the FileTransfer page. Source and destination platform must comply with each other.
Important! If you use this setting, you must not include additional attributes for the destination file as this will result in an error.
The following file attributes can be kept in BS2000 file transfers:
| Attributes Catalog Macro | Attributes File Macro |
|---|---|
|
|
Limitations to File Transfers with PAM Files
Important!
- When the BS2000 agent sends the file: All the pages are read if the PAM file is available in Non-Key (NK) format without an end being marked.
- When the BS2000 agent receives the file: When writing a PAM file, an end marker (an additional logical block) is attached. This block can occasionally destroy file structures.
Service Program for Remote Function Call (RFC) Tasks
The supplied files for the BS2000 agent include the service program UCYBRFC? for RFC tasks.
The INI file of the agent contains the section [RFC] with the parameter LOGON. Here you can set the parameter 1 to have the user ID considered in the file transfer. In this case, the agent generates a batch job for this user ID. This batch job calls the service program UCYBRFC? which connects to TCP/IP using the port that has been defined in the section [RFC] with the parameter PORT. This connection enables the agent to verify the access rights of the specified user for the particular file.
Creating this batch job causes a performance loss for the agent. Therefore, the RFC tasks are kept available for further file transfers. The RFC task ends automatically after a specified timeframe (parameter TIMEOUT=) when it has not received queries anymore. When the agent ends, all the corresponding RFC tasks too.
Important! The file UCYBRFC? must be shareable when the RFC mechanism is activated.
Creating, forming, and processing a data sequence is a complex process where script functions and statements, and specific objects cooperate closely. The following example describes a BS2000 OS command that is executed from a Script object. The result is written to the script's activation report line by line.
- Start the Script object SC.PROCESS.BS2000CMD with the following script:
- Host
The agent name where an event job is executed - in this case: C70. - EventJob
The job that should be executed - in this case EVENT.BS2000CMD.
Specifying BS2000CMD has the effect that the job EVENT.BS2000CMD starts.
Note: By default, client 0000 includes the following event jobs in the PREP_PROCESS folder of the Process Assembly perspective: EVENT.BS2000CMD, EVENT.BS2000UCON, EVENT.UNIXCMD, EVENT.UNIXFS and EVENT.WINCMD. You can use them as they are or adjust them for your own event jobs. - Filter
This parameter is not used. Therefore, the default value "*" is used and all output lines from the console command are considered. - Action
The value /STA P is assigned to the script variable &CMD of the event job. - UC_LOGIN=
The event job executes this command by using the Login object ADMIN. - The job EVENT.BS2000CMD starts.
- The job EVENT.BS2000CMD can now log in to run the console command.
- The scheduled command /STA P is stored in the script variable &CMD.
- SYSOUT is redirected to an output file and the command is executed.
- In the Script object SC.PROCESS.BS2000CMD, the script function PREP_PROCESS now returns a value. It refers to the administration data of the data sequence that should be processed.
:SET &HND# = PREP_PROCESS ('C70', 'BS2000CMD',,'CMD=/STA P','UC_LOGIN=Admin')
:PROCESS &HND#
: SET &LINE# = GET_PROCESS_LINE (&HND#)
: PRINT &LINE#
: ENDPROCESS
This script calls the function PREP_PROCESS which prepares the data sequence processing. The following parameters are assigned:
Important! In this job's Attributes page, activate the Display Attribute Dialog check box in the Runtime Parameters section. This action ensures the Include object ATTRDIA.BS2000 to be read. All attributes that are listed in the script of the Include object ATTRDIA.BS2000 can now be supplied with values. The Attribute Dialog is not displayed because the variable contents are passed on internally.
The output file is transferred to the Automation Engine and is then available as a data sequence. The execution of the job EVENT.BS2000CMD is complete.
This value is passed on to the script statement :PROCESS as a start parameter. :PROCESS and :ENDPROCESS form a processing loop which runs until the end of the data sequence is reached. During each iteration, a new line of this data sequence is read from the memory. By using the current value, the script function GET_PROCESS_LINE can retrieve the line content of the data sequence.
The script writes the current console line to the activation report.
Creating, forming, and processing a data sequence is a complex process where script functions and statements, and specific objects cooperate closely. The following example describes a BS2000 console command that is executed from a Script object. The result is written to the script's activation report line by line.
Important: To execute a BS2000 console command the UCYEBXXZ utility must be installed on the host. See Installing the Agent for BS2000.
- Start the Script object SC.PROCESS.BS2000UCON with the following script:
- Host
The agent name where an event job is executed - in this case: C70. - EventJob
The job that should be executed - in this case EVENT.BS2000UCON.
Specifying BS2000UCON has the effect that the job EVENT.BS2000UCON starts.
Note: By default, client 0000 includes the following event jobs in the PREP_PROCESS folder of the Process Assembly perspective: EVENT.BS2000CMD, EVENT.BS2000UCON, EVENT.UNIXCMD, EVENT.UNIXFS and EVENT.WINCMD. You can use them as they are or adjust them for your own event jobs. - Filter
This parameter is not used. Therefore, the default value "*" is used and all output lines from the console command are considered. - Action
The value BCDISP DISP=O is assigned to the script variable &CMD of the event job. - UC_LOGIN=
The event job should execute this command on the console and list all active applications. - The job EVENT.BS2000UCON starts.
- The job EVENT.BS2000UCON can now log in to run the console command.
- The utility UCYEBXXZ starts in the user ID that is specified in the Login object that you use in the job EVENT.BS2000UCON.
- It tries to establish one of the console connections that are included in the job's Process tab.
See the following example where the first parameter is the user ID, and the second the password: - The command BCDISP DISP=O is executed as soon as the connection to the console has successfully been established.
- The final message of the console command or the specified timeout end the connection. By default, the job EVENT.BS2000UCON includes the command TIM 120.
- In the Script object SC.PROCESS.BS2000UCON, the script function PREP_PROCESS now returns a value. It refers to the administration data of the data sequence that should be processed.
:SET &HND# = PREP_PROCESS ('C70', 'BS2000UCON',,'CMD=BCDSIP DISP=O')
:PROCESS &HND#
: SET &LINE# = GET_PROCESS_LINE (&HND#)
: PRINT &LINE#
: ENDPROCESS
This script calls the function PREP_PROCESS which prepares the data sequence processing. The following parameters are assigned:
Important! In this job's Attributes page, activate the Display Attribute Dialog check box in the Runtime Parameters section. This action ensures the Include object ATTRDIA.BS2000 to be read. All attributes that are listed in the script of the Include object ATTRDIA.BS2000 can now be supplied with values. The Attribute Dialog is not displayed because the variable contents are passed on internally.
CON CON1,CON1
CON CON2,CON2
CON CON3,CON3
CON CON4,CON4
CON CON5,CON5
CON CON6,CON6
CON CON7,CON7
CON CON8,CON8
The output file is transferred to the Automation Engine and is then available as a data sequence. The execution of the job EVENT.BS2000UCON is complete.
This value is passed on to the script statement :PROCESS as a start parameter. :PROCESS and :ENDPROCESS form a processing loop which runs until the end of the data sequence is reached. During each iteration, a new line of this data sequence is read from the memory. By using the current value, the script function GET_PROCESS_LINE can retrieve the line content of the data sequence.
The script writes the current console line to the activation report.