Platforms for CallAPIs

CallAPIs are supported for the platforms BS2000, Java, NSK, OS/400, SAP, UNIX, VMS, Windows, and z/OS. The required files are supplied with the Automation Engine and examples are provided for each platform. You can call all platforms either with your own program or with the corresponding utility.

Important! As of version 21, the Java and SAP CallAPIs use TLS/SSL to connect to the Automation Engine. They establish a connection to the new Java communication process (JCP)and use trusted certificates to prove their identity to other communication partners. All other CallAPIs still connect to the CP.

More information:

• Securing Connections to the AE (TLS/SSL)

• TLS/SSL Certificate Considerations

• Types of Server Processes

For additional information about the different certificate types and examples of how they could be created and used, see What Kind of Certificates Should I Use for Automic Automation v21.

Important! Please note that these are only examples, not a requirement for Automic Automation and they are not meant to replace the product documentation.

In Automic Automation Kubernetes Edition, CallAPIs establish a connection to a TCP load balance. The address of the load balancer must be defined on both sides: the Automation Engine and the CallAPI. The only exceptions are the CallAPIs for Java and SAP, which must be upgraded to use TLS/SSL to connect to the Automation Engine. These two CallAPIs establish a connection with the Java communication process (JCP) through an HTTPS load balancer.

More information:

• Container-Based Installation - Automic Automation Kubernetes Edition

• Connecting to the AAKE Cluster

CallAPI for BS2000

You define the code table that should be used in the INI file of the CallAPI for the Agent BS2000 by entering the name of the CodeTable object in the codetable= parameter of the [GLOBAL] section.

Use Your Own Program

You can assign all parameters that are required with your own program. The only requirement is that it must include the UCCALL3 module, or dynamically reload it at runtime. For more information, see Using the CallAPI with your Own Program.

Use the Utility

The supplied package includes the UCXBB2?C utility. You can use it in BS2000 procedures or batch jobs. For more information, see Using the CallAPI Utility (ucxbxxxc).

The utility reads the data that is required for logging in to the Automation Engine through SYSDTA. The AE Script that should be executed can either derive from a file or directly from SYSDTA. If you use a file, you must assign it before the program is called by using the link name UCSCRIPT.

Examples

In the first example, the link name UCSCRIPT is not assigned. The AE Script that should be executed is read until it reaches the SYSDTA command /EOF.

/FILE UCXBB22C.INI,LINK=INI
/EXEC UCXBB22C
04,RS,PROG,PASSWORD
:SET &RUNNR = ACTIVATE_UC_OBJECT(JOBS,EXAMPLE1)
:IF &RUNNR = '0000000'
: SET &ERROR = SYS_LAST_ERR_NR
: SET &ERROR = SYS_LAST_ERR_NR
: STOP MSG,51,'ACTIVATION ERROR: &ERROR'
:ELSE
: STOP NOMSG,50,'THE JOB WAS STARTED WITH RunID &RUNNR'
:ENDIF
/EOF

The script that should be executed is available in the file MY.SCRIPT.FILE:

/FILE UCXBB22C.INI,LINK=INI
/FILE MY.SCRIPT.FILE,LINK=UCSCRIPT
/EXEC UCXBB22C
04,RS,PROG,PASSWORD

The following example returns the RunID, the error code, and the error message from the CallAPI. These three values are written in a job variable (JV). 

/CREATE-JV JV-NAME=#UC.RETCODE
/SET-JV-LINK LINK-NAME=UCRETC,JV-NAME=#UC.RETCODE
/CREATE-JV JV-NAME=#UC.RETTEXT
/SET-JV-LINK LINK-NAME=UCRETT,JV-NAME=#UC.RETTEXT
/CREATE-JV JV-NAME=#UC.RUNID
/SET-JV-LINK LINK-NAME=UCRUNID,JV-NAME=#UC.RUNID
/EXEC UCXBB23C
*INI
:SEND_MSG RS,DEV,'MESSAGE FROM THE BS2000 CALL INTERFACE &NAME.'
/EOF
/SHOW-JV JV-CONTENTS=*LINK(LINK-NAME=UCRUNNR)
/STEP
/SHOW-JV JV-CONTENTS=*LINK(LINK-NAME=UCRETC)
/SHOW-JV JV-CONTENTS=*LINK(LINK-NAME=UCRETT)

CallAPI for Java

Important! As of version 21, the CallAPI for Java uses TLS/SSL and establishes a connection to the new Java communication process (JCP), see Securing Connections to the AE (TLS/SSL)

Use Your Own Program

See Using the CallAPI with your Own Program.

Use the Utility

You can call the UCCALL3.JAR file from the command line, or from a batch file. A sample file (UCCALL3.BAT) that explains how you call it from a batch file is supplied with the AE files. For more information, see Using the CallAPI Utility (ucxbxxxc).

Example

The CallAPI is called with the login data of client 0098 and can be accessed without using a password. The following example activates an AE Script which is stored in the file SCRIPT.TXT.

java -jar uccall3.jar script=script.txt logon=98,smith,uc4

CallAPI for NSK

Use Your Own Program

See Using the CallAPI with your Own Program.

Use the Utility

The utility UCXBNS1C is part of the AE package. You can call it from the command line of the relevant operating system, from a script or a job. For more information, see Using the CallAPI Utility (ucxbxxxc)

Examples

The first example calls the utility with the connection and login information that is specified in the form of parameters. The utility reads the processing instructions (AE Script) from a file called SCRFILE.

run ucxbns1c script=SRCFILE LOGON=1000,SMITH,UC4

The second example calls the utility with the specified script file. Connection and login data, and additional information are read from the INI file.

run ucxbns1c script=SRCFILE INI=UCXBNS1I

CallAPI for OS/400

Use Your Own Program

See Using the CallAPI with your Own Program.

Use the Utility

The supplied utility UCXBO41C is available in the library and may be used in OS/400 CL scripts. For more information, see Using the CallAPI Utility (ucxbxxxc).

The AE Script that should be executed is read from a file member.

Example

The libraries are adjusted to your AE installation.

CALL PGM(UC4/UCXBO41C) +
PARM('INI=UC4/INI(UCXBO41C)' 'LOGON=<your four-digit client number>,<your user>,<your department>,<your password>' 'SCRIPT=UC4/INI(SCRSAMP)')

CallAPI for SAP

Important! As of version 21, the CallAPI for SAP uses TLS/SSL and establishes a connection to the new Java communication process (JCP), see Securing Connections to the AE (TLS/SSL)

The RFC Server transfers the script to the AE system. It includes a function module called UC4 which you can call in your ABAP programs.

The SAMPLE folder of the delivery package includes sample programs which explain how you can use it. For more information, see Using the CallAPI Utility (ucxbxxxc).

Function Module UC4

Sound knowledge of ABAP/4 is required to understand the following descriptions:

Import Parameter

• client(4) type n

  AE client

• trcflg(1) type c

  Trace flag

• userabtl(200) type c

  Department of the AE user

• username(200) type c

  Name of the AE user

• queue(200) type c
  (Optional) Name of the queue, for example CLIENT_QUEUE

• userpass(32) type c

  Password of the AE user

Export Parameter

• msg(255) type c

  Message

• run(10) type c
  Run ID of the scripts

Tables

• script

  Script table (a total of 255 characters per line)

  Example

  TYPES:
  BEGIN OF scriptline,
  script(255) TYPE c,
  END OF scriptline.

  DATA:
  uc4_script TYPE TABLE OF scriptline WITH HEADER LINE.

Exceptions

• logon-failed

  Logging in to AE was not successful

• others

  Other error

Example

Call the function module:

call function 'UC4' destination 'UC4'
exporting
client = p_clint
trcflg = '0'
userabtl = p_usera
username = p_usern
userpass = p_userp
importing
msg = omessg
run = orunnr
tables
script = uscript
exceptions
logon_failed = 1
others = 99.

CallAPI for UNIX

Use Your Own Program

The UCXBXXXC.c program is available as C source code. The corresponding structure definitions are stored in the UCCALL3.h file . These files and the MakeFile for compiling the example are available in the /src directory. Update the supplied example with your data. Adjust the MAKEFILE_EXAMPLE.??? MakeFile to your environment. Rename it to MAKEFILE and then you can call it with make because MAKEFILE is the default name. Now you can generate an EXE file and test the CallAPI. For more information, see Using the CallAPI with your Own Program.

Use the Utility

The UCXB???C utility is supplied with the AE files. You can either call it from the command line or from an executable file. For more information, see Using the CallAPI Utility (ucxbxxxc).

AE Script is used to define processing steps which are assigned as default input when the program is called: The entry < file name reads the AE Script from the corresponding file. The entry <<EOF_SCRIPT reads the AE script from the command line until the text EOF_SCRIPT is recognized.

Examples

In the first example, the utility is called with the AE Script being read from the script.txt file. Connection and login specifications are read from the INI file.

./UCXBUI5C SCRIPT=./script.txt

In the second example, the connection and login specifications are passed from the CallAPI.

./ucxblx6c SCRIPT=script.txt LOGON=0001,SMITH,DEV, aerox

CallAPI for VMS

Use Your Own Program

The UCXBVXXC.C program is available as C source code. The corresponding structure definition is stored in the UCCALL3.H file. A command for compiling the example is available in MAKEXAMP.COM. Update this example with your data and adjust it to your environment. In doing so, you can generate an EXE file, and can test the CallAPI. For more information, see Using the CallAPI with your Own Program.

Use the Utility

The delivery package includes the UCXBV??C.EXE utility which you can call from a command file. For more information, see Using the CallAPI Utility (ucxbxxxc).

Processing steps that are defined with AE Script are read by the standard input.

CallAPI for Windows

Use Your Own Program

See Using the CallAPI with your Own Program.

Use the Utility

No installation is required for using the CallAPI but you need to make sure that the utility can access the UCXBWI3C.DLL file. For more information, see Using the CallAPI Utility (ucxbxxxc).

Example

In the following example, the utility is called with the login data of client 0098. Access is possible without a password. The aim is to activate an AE Script which is stored in the file SCRIPT.TXT.

UCXBXXXC SCRIPT=SCRIPT.TXT LOGON=98,SMITH,UC4

CallAPI for z/OS

You define the code table that should be used in the INI file of the z/OS CallAPI. Enter the name of the CodeTable object in the [GLOBAL] section, parameter codetable=. If this parameter is empty, the IBM default code table is used.

Use Your Own Program

See Using the CallAPI with your Own Program.

Use the Utility

The delivery package includes the UCCALL4 utility which you can use in z/OS jobs. You find it in the load library. For more information, see Using the CallAPI Utility (ucxbxxxc).

The AE Script which should be processed in the Automation Engine is read from SYSIN. You can also use the data definition instead of the dataset names as you can see in the following examples.

If the utility should be used in a job, the user must be authorized to communicate through TCP/IP.

The REGION= parameter should be set at least to 65M as otherwise, errors will occur.

Examples

Dataset names must be adjusted to your installation and z/OS configuration.

The latest CallAPI, version 4, is written in LE C and supports AES encryption and IPv6:

//UC4JOB   JOB ......
//UCCALL   EXEC PGM=UCCALL4,
//    PARM='INI=FLQ.UCXBM25C.INI LOGON=<your four-digit client number>,<your user>,<your department>,<your password>'
//STEPLIB  DD DSN=FLQ.UCXJM25.LOAD,DISP=SHR
//*        You can use the following command
//*        instead of the PARM INI=AE-inifile
//*UCINI    DD DSN=AE-inifile,DISP=SHR
//SYSIN    DD *
:SET &RUNNR = ACTIVATE_UC_OBJECT(JOBS,ExampleL1)
:IF &RUNNR = '0000000'
:   SET &ERROR = SYS_LAST_ERR_NR
:   STOP MSG,51,'ACTIVATION ERROR: &ERROR'
:ELSE
:   STOP NOMSG,50,'JOB WAS STARTED WITH RunID &RUNNR'
:ENDIF
/*
//

See also:

• CallAPI Overview
• Installing the CallAPIs