aXesTerminalService Example
This example will automate a 5250 session, utilising the maintenance programs shipped with the Personnel Demo System, to insert Employee details into the PSLMST file.
In order to demonstrate how to use the Commands and Keywords for the aXesTerminalService, the following sample code written in LANSA is provided using the JSMX (RDMLX) BIFs.
Note: This example inserts a new employee using the Employee ID A9090. The employee id must be unique in the personnel system files. You must ensure that it does not already exist. Each time you execute the example, you must delete the employee record before executing the example again, or change the employee id used in the code and recompile the function.
Note: This example deliberately uses very limited exception handling code in order that the main program steps might remain clear.
To use this example, you must:
1. Identify the name of a user profile that has access and authority to the LANSA demonstration personnel system. In addition, the example code as supplied makes the following assumptions:
- the user's initial menu includes a command entry line at row 18, column 7 (where the example program will type the LANSA command to start the personnel system employee entry function)
- the user is authorised to use the commands (LANSA and SIGNOFF)
- the user's initial library list includes the necessary LANSA libraries.
If any of these assumptions are not correct for the user you have chosen, you may to change the supplied example code accordingly.
2. Identify the following details necessary to connect to the aXes Terminal Server on your system:
| HOST |
The host name of the aXes TerminalServer in your environment. You can usually use the network name of the IBM i system on which aXes is installed and running. |
| PORT |
The port number on which the aXes Terminal Server is listening. By default aXes listens on port 80. |
| USER |
The name of the IBM i user profile defined on the HOST system that you identified above |
| PASSWORD |
The password for the user profile specified by the USER keyword. |
3. Change the code in the example that builds and executes the CONNECT service command to use the details you identified above.
* -----------------------------------------------
* Process ........: Tutorial
* Function .......: AXES001
* Created on .....: July 13, 2011
* Description ....: Utilising the AxesTerminalService
* -----------------------------------------------
Function Options(*DIRECT)
* If these required fields are already defined in the repository then comment or remove these definitions
Define Field(#jsmsts) Type(*char) Length(20)
Define Field(#jsmmsg) Type(*char) Length(255)
Define Field(#jsmxhdle1) Type(*char) Length(4)
Define Field(#jsmxcmd) Type(*char) Length(355)
* Field to receive the aXes screen name from the aXesTerminalService
* (not used in this example program, but included for illustration)
Define Field(#AXSCREEN) Type(*Char) Length(256)
* Dummy working list used to exchange fields with the JSM
Def_list Name(#EXCHANGE1) Fields(#AXSCREEN) Type(*Working) Entrys(1)
* -----------------------------------------------
* Program Mainline
* -----------------------------------------------
* Open a connection to the JSM
Use Builtin(JSMX_OPEN) To_Get(#JSMSTS #JSMMSG #jsmxhdle1)
Execute Subroutine(CHECK_STS) With_Parms(#jsmxhdle1)
* Load the aXesTerminalService
#JSMXCMD := 'SERVICE_LOAD'
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD 'SERVICE' 'AXESTERMINALSERVICE')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD 'TRACE' '*YES')
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXHDLE1)
* Connect to the aXes server
* NB: PLEASE CHANGE CONNECTION DETAILS TO SUIT YOUR ENVIRONMENT
* NOTE THE USE OF THE #EXCHANGE1 DUMMY WORKING LIST TO EXCHANGE
* FUNCTION FIELD VALUES WITH THE SERVICE. (THE FIELDS ARE NOT
* USED IN THIS EXAMPLE.) YOU COULD ADD 'SERVICE_EXCHANGE(*FIELD)'
* TO THE JSM COMMAND STRING FOR SIMILAR EFFECT.
* IN THIS CASE, THIS ALLOWS US TO RECEIVE THE AXES SCREEN NAME
* OF THE RESULTING 5250 SCREEN INTO THE FUNCTION FIELD #AXSCREEN.
#JSMXCMD := CONNECT
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD HOST 'MYSERVER')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD PORT '80')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD USER 'MYUSER')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD PASSWORD 'MYPASSWORD')
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD #EXCHANGE1) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Send (Press Enter) Command to continue
* (This is in case the "Display Program Messages" display is shown)
* (NOTE AGAIN THE USE OF THE #EXCHANGE1 DUMMY WORKING LIST)
#JSMXCMD := SEND
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD #EXCHANGE1) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Start LANSA to execute the Enrol function in PSLSYS Process
* (NOTE AGAIN THE USE OF THE #EXCHANGE1 DUMMY WORKING LIST)
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '18')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '7')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD SENDKEY ENTER)
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE("LANSA REQUEST(RUN) PROCESS(PSLSYS) FUNCTION(ENROL) PARTITION(DEM) LANGUAGE(ENG)")') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD #EXCHANGE1) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Employee ID
* NB: Employee ID used must NOT be already used
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '3')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(A9090)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Surname
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '4')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(Smith)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Given Name
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '5')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(John)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Street Address
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '6')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(1 Some Street)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Suburb
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '7')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(Sometown)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the State and Country
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '8')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(CCC)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Zip code
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '9')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(7111)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Home Phone Number
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '10')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(1222222)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Business phone Number
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '11')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(133333)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Department Code
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '12')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(ADM)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Section Code
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '13')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(04)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Employee Salary
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '14')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(31222)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the Start Date
* AND press ENTER to submit the details
* (NOTE AGAIN THE USE OF THE #EXCHANGE1 DUMMY WORKING LIST)
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD SENDKEY ENTER)
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '15')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '43')
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE(100311)') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD #EXCHANGE1) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Press F3 to return to the main menu
* (NOTE AGAIN THE USE OF THE #EXCHANGE1 DUMMY WORKING LIST)
#JSMXCMD := SEND
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD SENDKEY F3)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD #EXCHANGE1) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Type the SIGNOFF command and press ENTER
#JSMXCMD := SETBYPOS
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD ROW '18')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD COL '7')
Execute Subroutine(KEYWRD) With_Parms(#JSMXCMD SENDKEY ENTER)
Use Builtin(TCONCAT) With_Args(#jsmxcmd ' VALUE("SIGNOFF")') To_Get(#JSMXCMD)
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Disconnect from the aXes terminal server
#JSMXCMD := DISCONNECT
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXCMD)
* Unload the aXesTerminalService
#JSMXCMD := 'SERVICE_UNLOAD'
Use Builtin(JSMX_COMMAND) With_Args(#JSMXHDLE1 #JSMXCMD) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXHDLE1)
* Close the connection to the JSM
Use Builtin(JSMX_CLOSE) With_Args(#JSMXHDLE1) To_Get(#JSMSTS #JSMMSG)
Execute Subroutine(CHECK_STS) With_Parms(#JSMXHDLE1)
Return
* -----------------------------------------------
* Subroutine to build JSM commands
* -----------------------------------------------
Subroutine Name(KEYWRD) Parms((#W_CMDX *BOTH) (#W_KEYWRD *RECEIVED) (#W_KEYVAL *RECEIVED))
Define Field(#W_CMDX) Reffld(#JSMXCMD)
Define Field(#W_KEYWRD) Reffld(#STD_TEXT)
Define Field(#W_KEYVAL) Length(255) Reffld(#STD_TEXTL)
#W_CMDX += ' ' + #W_KEYWRD + '(' + #W_KEYVAL + ')'
Endroutine
* -----------------------------------------------
* Subroutine to check the JSM status
* -----------------------------------------------
Subroutine Name(CHECK_STS) Parms(#W_HDLE)
Define Field(#MSGDTA) Type(*CHAR) Length(132)
Define Field(#W_HDLE) Type(*CHAR) Length(4)
If Cond('#JSMSTS *NE OK')
#MSGDTA := 'Error Status Code: ' + #JSMSTS
Message Msgid(DCM9899) Msgf(DC@M01) Msgdta(#MSGDTA)
#MSGDTA := 'Error Message: ' + #JSMMSG
Message Msgid(DCM9899) Msgf(DC@M01) Msgdta(#MSGDTA)
Endif
Endroutine