Novell Home

AS400 Basics for Platform Receiver and IDM

Novell Cool Solutions: AppNote
By Nicolas Barberis

Digg This - Slashdot This

Posted: 23 Mar 2006
 

Note: I had no previous knowledge on AS400, so I had to learn on the go. I wrote this guide as a reminder for future projects and as a guide to others. Hopefully it will help you.

AS400 Navigation Basics

Figure 1 - AS400 screen

Navigation through fields is done with TAB key. So you would type your username, [TAB], your password [ENTER]. That seems obvious, but will save you a lot of failed logins.

The next screen you'll see is the initial menu that's assigned to your profile. We will see more information on that later. You'll also notice the line '===> _____', that's where you type your commands and options. If you want to access an option from the menu, type the number (ie. 90 [ENTER] for login out). You can also type your commands from here. These commands will take you to other options that are not necessarily shown on the menu.

AS400 commands use the following IBM convention: CL command names are a shorthand form of the standard grammar for an English language imperative statement. Each command is an instruction to the computer to perform an action. The commands consist of a verb, or action, followed by the subject that will be acted upon.

The following table shows the verb abbreviations.

EnglishCL AbbreviationEnglishCL Abbreviation
AddADDHoldHLD
AllocateALCInitializeINZ
CallCALLMoveMOV
ChangeCHGOverrideOVR
ClearCLRReorganizeRGZ
CopyCPYReleaseRLS
CreateCRTRemoveRMV
DeclareDCLRestoreRST
DeleteDLTRetrieveRTV
DoDOSaveSAV
DisplayDSPSendSND
EndENDStartSTR
Go ToGOTOWork WithWRK

Then you have the subjects:

EnglishCL AbbreviationEnglishCL Abbreviation
AttributeAJobJOB
AuthorityAUTLibraryLIB
ConfigurationCFGListL
CommandCMDMemberM
CommunicationCMNMessageMSG
DescriptionDObjectOBJ
DisketteDKTProgramPGM
DocumentDOCQueueQ
EntryESubsystemSBS
FileFSystemSYS
FolderFLRTapeTAP

We will we working mainly with those highlighted. By using the verb and subject charts, you can easily determine the verb and subject to combine to produce a completed CL command. For example, if you want to "create a command," you can see by referring to the charts that the verb for create is CRT and the subject for command is CMD. Therefore the complete CL command would be CRTCMD. Similarly, if you want to "display a job," the command is DSPJOB.

Many CL commands use the verb, adjective, subject format. For example, to create an RPG/400 program, the CL command is CRTRPGPGM (Create RPG Program); to create a COBOL/400 program, the CL command is CRTCBLPGM (Create Cobol Program); and to create a standard CL program, the command is CRTCLPGM (Create CL Program). In these cases, the adjective qualifies the subject by specifying the kind of program to be created.

For help identifying and using OS/400 commands, try using one or more of the following methods:

  • On any command line, press F4 (Prompt). OS/400 will present you with a menu of the major command groups. You can choose menu options to find and select the command you need.
  • On any command line, type Go Cmdxxx, filling in the xxx with either a verb or an object - for example, Go CmdPTF for PTF-related commands or Go CmdWrk for "work with" commands. OS/400 will present you with a list of those commands.
  • Type a generic name directly on the command line (e.g., Wrk*, Str*, CrtDev*) and press Enter. OS/400 will present you with a list of commands that start with the same letters you specified before the asterisk.
  • Type a command on the command line and press F1 (Help). OS/400 offers online help for all system commands.

Note: You can also execute the SltCmd (Select Command) command to find commands using a generic name (e.g., Str*, Wrk*). We don't recommend using this command, though; it's too easy to accidentally type D instead of S as the first character in the command - that's right, DltCmd Wrk*! Oops!!

Platform Receiver Commands

Basically we will be using the following commands which proved to be the most useful regarding the Platform receiver for AS400.

CommandDescriptionRelates to
EDTLIBLEdit library list.We need to edit our user's library list to add ASAM library. You'll see the library list, then you move to the first free slot and type ASAM [ENTER]
WRKMBRPDMWork with members using PDMBy specifying SCRIPTS in file and ASAM in library, we can edit and compile the scripts that ship with IDM.
EDTFEdit FileIn case we need to edit the attribute mapping, we will be using the EDTF '/usr/local/ASAM/data/AttrMap.conf' command.
QSHQ Shell accessThis command will give us access to the command line so that we can navigate the file system as with any UNIX.
DSPJOBLOGDisplay Job LogWe will be using this command a lot. Through this command we can debug our scripts and also check on the operations status. DSPJOBLOG JOB(ASAMRCVR) calls the log specifically for the ASAM receiver job.
CHGUSRPRFChange user preferencesThis command allows us to either call the screen where we can make our changes to any user, or directly modify the user by specifying everything from the command line.

This might be confusing if you are just starting, but these are the fields that comprise the user object. We will reference this table later on.

DescriptionField NameDescriptionField Name
User ProfileUSRPRFGroup Authority TypeGRPAUTTYP
User Password PASSWORD Supplemental Groups SUPGRPPRF
Password Expired PWDEXP Accounting Code ACGCDE
Status STATUS Document PasswordDOCPWD
User class USRCLS Message Queue MSGQ
Assistance Level ASTLVL Library
Current Library CURLIB DeliveryDLVRY
Initial program to call INLPGM Severity Code filter SEV
Library Print Device PRTDEV
Initial Menu INLMNU Output Queue OUTQ
Library Library
Limit Capabilities LMTCPB Attention Program ATNPGM
Description TEXT Library
Special Authority SPCAUT Sort Sequence SRTSEQ
Special Environment SPCENV Library
Display Sign-on Information DSPSGNINF Language ID LANGID
Password Expiration Interval PWDEXPITV Country ID CNTRYID
Limit Device Sessions LMTDEVSSN Coded Character set ID CCSID
Keyboard Buffering KBDBUF Character Identifier Control CHRIDCTL
Maximum allowed Storage MAXSTG Locale Job attributes SETJOBATR
Highest schedule priority PTYLMT Locale LOCALE
Job description JOBD User Options USROPT
Library User ID Number UID
Group Profile GRPPRF Group ID Number GID
Owner OWNER Home Directory HOMEDIR
Group Authority GRPAUT

Basic Platform receiver operation is described on the documentation, so I'm going to focus more on the other activities related to the driver.

Editing Files

When editing files, either source code, with EDTF or through a menu, you have to know how to do that - it's not intuitive. On the left you'll see a column. To insert a new line, type 'I' on top of those numbers and press ENTER. If you want to add more lines, type 'I2' for two lines, and so on. The lines will be added after the current line. To delete lines, type D on that column and press ENTER. To delete more than one line just type the number after the D, like 'D2' for deleting 2 lines.

Figure 2 - Editing lines

You send the actual information when you press ENTER. So after typing your lines, be sure to press the ENTER key. To save the file, press F2 and F3 to exit.

Platform Configuration File

You can either modify this file by issuing the command 'edtf '/usr/local/ASAM/data/asamplat.conf' or by 'go asam' and selecting option 1, Modify Configuration. One important option is 'TRACEFILE'. You can use this information for debugging purposes. This file tends to grow a lot, so be careful with its use. The correct parameter is 'TRACEFILE {file}', where file could be '/tmp/trace.log'. You can access that file later through FTP. Always check with the system administrators on anything that you might be doing. If the FTP service is not running, you can load it with 'STRTCPFTP' command.

For changes to have effect you must stop and restart the platform receiver. Do so from the 'go asam' menu.

Joblogs - Basic Information

As stated on the documentation, you can use the standard OS/400 joblogs. You can access those with DSPJOBLOG. One thing that's not specified is how to do that - you have to specify the job.

1. Access the logs by issuing the command 'DSPJOBLOG JOB(ASAMRCVR)'. You'll see the command line that executes the ASAM Receiver Job.

2. Press F10 and F5 to see detailed messages and to refresh the screen. Now you have the log information.

3. Press PgUp and PgDn to navigate the file - you'll see how each script sends its output there. For example, you can see 'ADDUSR: Starting', and that would be when the ADDUSR script was called and it sent a program message with that text. You will also see the commands that those scripts execute. This is a great start point for debugging information.

Figure 3 - Detailed messages from the joblog

Adding Attributes for Synchronization

You might need to add more information than what's included on the default configuration. Let's say that you extend the schema and add an attribute called ASAM-ACGCDE. There are several steps to follow to do this.

1. Modify the Accounting information on AS from the eDirectory and have that synchronized.

2. Add that attribute to the filter on the IDM driver.

3. Restart the driver.

4. Map that attribute to its corresponding attribute on AS as shown in the next steps.

5. Edit the attribute mapping file that resides on the AS platform - from the command line execute 'edtf /usr/local/ASAM/data/AttrMap.conf'. You will see a list of attributes separated by comma where the first column is the LDAP attribute and the right value is the AS attribute.

6. When you change this information, restart the platform receiver for changes to take effect.

7. Edit the scripts so the information actually goes where it should. If it's user information, then you probably want to modify the ADDUSR and MODUSR scripts. We will access the scripts through the WRKMBRPDM command. If you must specify the file and library, these are SCRIPTS and ASAM respectively.

Figure 4 - AS400 screen

From this screen you can edit, copy, create, remove, rename, compile and view the scripts. To edit one of the scripts, you go to the OPT column and type "2" and press Enter on it. That will take you to the edit screen.

Modifying the ADDUSR Script

Now we will modify the ADDUSR script so that it will use the accounting code attribute that we've just added. The program starts after the PGM statement and ends with the ENDPGM statement.

1. Define a runtime variable by inserting a new line ('I' on the column with the line numbers) on the beginning following the DCL statements.

2. Type 'DCL VAR(&ACGDE) TYPE(*CHAR) LEN(25)'. This means that we are declaring (DCL) a new variable (VAR) named ACGCDE, of type character (*CHAR) and of length (LEN) 25.

3. For every variable that is the same, you must call the program GETASAMVAR with three values: the name of the AS400 value that's on the AttrMap.conf file, the variable where you want it to be stored, and the length of the variable. So we'll add this:

CHGVAR VAR(&LEN) VALUE(25)
CALL PGM(ASAM/GETASAMVAR) PARM('ACGCDE' &ACGCDE &LEN)

The first line will change the LEN variable value to 25, which is the maximum length that we've defined for that attribute. The second line calls the GETASAMVAR program that will get the variable value. We sent the first parameter 'ACGCDE' so that it knows what LDAP variable to get. The second parameter &ACGCDE states that the result must be returned on that variable that we've declared on the beginning, the last parameter is the length of the value returned.

So, after that line get's executed we have, if available, the value of the eDirectory attribute on this variable. But what if there is no value? We need to check the returned value so as not to mess up the current AS data. The GETASAMVAR returns the length of the value on the &LEN variable. If no value was returned, then it will be 0.

4. Add this next to the last code:

IF COND(&LEN *EQ 0) THEN(DO)
   CHGVAR VAR(&ACGCDE) VALUE('*SAME')
ENDDO

This will first check if the LEN variable is equal to 0. If it is, then we change the value of the ACGCDE variable to be '*SAME', which means to AS 'don't change the value'. So when we actually execute the modify we won't be modifying that. We don't want to be changing the original script, so we'll add new commands to the existing script, so that if our modifications fail, the script still works.

5. Navigate the script until you find a line that says 'CGHVAR VAR(&CMD) VALUE('ADDIRE ')'. This line starts the creation of the CMD variable that will modify the directory information of the AS 400.

6. Leave it alone and keep going until the line that says 'CALL PGM(ASAM/SETASAMVAR) PARM('RC' '000')'. That's the line that tells the IdM driver that the script ran correctly. We'll add our next modifications after this.

7. Insert a new line by typing 'I' on the left column with the line numbers and pressing Enter.

8. Create your own command variable by typing:

CHGVAR VAR(&CMD) VALUE('CHGUSRPRF ' *CAT +
      'USRPRF(' *CAT &TARGETUSER *TCAT ') ' *CAT +
      'ACGCDE(' *CAT &ACGCDE *TCAT ') ')
SNDPGMMSG MSG(&CMD)
CALL PGM(QCMDEXC) PARM(&CMD 1024)
What does it all mean? Well, this is the complicated part - back to the more "advanced basics." You can modify user's information with commands. The command used to modify the user object information is CHGUSRPRF (change user preferences). This command requires at least the target user and a modification to some attribute. In this case we want to create a command that looks like this:
CHGUSRPRF USRPRF({theuser}) ACGCDE({new_accounting_value})

8. Modify the variable CMD where we will be storing a string. It starts with 'CHGUSRPRF' and we then add the 'USRPRF(' string followed by the contents of the &TARGETUSER variable.

9. Add the 'ACGCDE(' part of the string that will actually tell the command CHGUSRPRF to modify the value of that attribute.

10. Insert the content of the &ACGCDE value and close with a ')'.

11. Use the SNDPGMMSG statement to send (SND) a Program (PGM) Message (MSG). And the message is the content of the CMD variable that we've just created. This will send the command to be executed to the log so that we can later see that it's being created as we've planned.

The last line calls the program QCMDEXC that will execute the contents of the variable CMD as if a user were typing it. If we did things the right way, then what we have here is a modify of the user object, just created, with the new value, or *SAME, with the value of the eDirectory ASAM-ACGCDE attribute. Isn't this a piece of cake?

12. Press F3 to exit the editor.

13. Save the changes by typing 'Y' on the first field that's shown when you exit.

14. Press Enter to return to the WRKMBRPDM screen.

15. Under the column 'type' type CLP next to the recently modified script. This will tell the AS400 that this is a CL program.

16. On the option column, next to the recently modified script, type '14' (compile) and press Enter. A word of advice: you might want to immediately press F3 to exit the screen; if the compilation fails, you'll be stuck in that screen.

Checking the Compilation Results

1. Type the command WRKSPLF which will be 'work with spool file'.

2. Press PgDn until you reach the bottom of the list - you'll probably see an ADDUSR file.

3. Move to the left column, type '5' (view) and you'll see what the compiler did.

4. Navigate with PgDn. If there are any errors, they will be shown with the error description and error severity. A severity of 10 it's ok. But a severity of 30 or more won't compile and won't replace the program. I won't go further into this, because it's too much information for this introduction article.

Now you have to do exactly everything again for the modify script. It's MODUSR. Just add the lines as they are on the ADDUSR script and it should work just fine. Try it and remember to check the 'DSPJOBJOG JOB(ASAMRCVR)' to see your messages.

References

  • 'Control Language Programming for the AS/400, Second Edition', by Bryan Meyers and Dan Riehl
  • 'Starter Kit for the IBM iSeries & AS/400', by Gary Guthrie and Wayne Madden


Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions. www.webwiseone.com

© 2014 Novell