There are three words that you need to remember when dealing with any computer system, including the iSeries 400. They are backup, backup, and backup. If you want a restful night’s sleep, you’d better have a good backup of your data files, programs, and operating system.

But there are other management issues. For instance, if you are an application service provider (ASP), redundancy is an important issue. In today’s computing environment, downtime is not acceptable. If your customers experience an interruption in service, they may be someone else’s customers tomorrow. Consequently, if disaster strikes and your computer goes down, you need to be ready to automatically switch to an alternate server and continue running as if nothing had happened. In order to accomplish this lofty goal, you will need to find ways to replicate software, data, and other system objects, such as user profiles. In this article, we will deal with the last of these items.

User Profiles

One of the many challenges we addressed in our quest to become an ASP was how we were going to keep identical user profiles on separate iSeries 400 computers. In other words, when we added a new user to our primary system, we wanted that system to automatically call a program that would add the same user profile to our backup system. We accomplished this goal using two distinctive and infrequently used features of the iSeries 400 computer: exit points and remote data queues.

In this article, we will cover the basics of using an exit point to call a program automatically whenever a user performs a certain function. In our example, this will occur whenever a new user profile is added to the system. We will also discuss how you can use remote data queues to pass information from one system to another automatically. In our case, we will use remote data queues to pass the information about a newly created user profile from the primary system to a backup system.

Here We Go

Right off the bat, we are going to assume that you already have two iSeries 400 computers connected and “talking” to one another. We are not going to cover the mechanics of doing this.

When replicating user profiles on the iSeries 400, the first challenge is determining when a user profile is created on the primary system. One approach we could employ is to create a program that lists all of the user profiles on both systems to compare the differences. But this method would likely not run in a real-time environment, and, therefore, the user profiles on the two systems would rarely be in sync all of the time. The user profiles would be synchronized only up to the last date and time at which the synchronization program ran.

We wanted the system to run the synchronization program automatically whenever someone added a new user to the system. Fortunately, there is an exit point that provides this very capability. An exit point is a place (or point) in a system process at which the system will pause and call a user-written program. This user-written program is called an exit program. Figure 1 shows the partial code of an exit program that will get called every time a new user is added to the primary system.

You may be asking yourself how we told the system to run our program at a predefined exit point. The answer is that we do it by registering the exit point. Take a moment to look at the following command:

ADDEXITPGM +

EXITPNT(QIBM_QSY_CRT_PROFILE) +

FORMAT(CRTP0100) +

PGMNBR(*LOW) +

PGM(xxx/PGM001RG)

The Add Exit Program (ADDEXITPGM) command causes the sample program (PGM001RG) to execute whenever a new user profile is created.

Whether you were aware of it or not, there are many exit points on your system. If you are curious, simply run the Work with Registration Information (WRKREGINF) command. You will see a rather substantial list of exit points. You can attach exit programs to any of the exit points you see on this substantial list. Note that you could have more than one program called at each exit point. The sequence number you assign when you register your program will determine the order in which the exit programs get called.

Notice that we assigned the exit program in our example to the QIBM_QSY_CRT_PROFILE exit point. That is the exit point for which a user profile is created on your system. We chose this exit point because we were only interested in running our program when a user profile was added to the primary system. But also note the QSY_DLT_PROFILE and the QSY_CHG_PROFILE exit points. What do you suppose these exit points control? Depending on your environment, you may want to write your own exit programs for these delete user profile and change user profile exit points.

Boogie (with Exit Points)

The code snippet shown in Figure 1 is a subset of the complete program available at www.midrangecomputing.com/mc. Take a closer look at how this program works. The InData parameter that the system passes to the program is a 38-byte data structure in the format that this exit point delivers data to a program. You will find that part of the fun when dealing with exit points is “discovering” the documentation that defines the format of the parameters. There is not a single, central place that defines all of the exit points and their parameters. You have to dig through the manuals to find the gems.

In this particular case, the gem is the user profile name located in the last 10 positions of the data structure. Armed with this critical piece of information, we call the QSYRUSRI API, passing the user profile name to it and receiving back almost all the information in the user profile. The returned information is placed into a receiver variable (Receiver1) that we send over to the second machine using the QSNDDTAQ API. We’ll cover this technique in more detail in this article.

In Figure 1, you will see that the program calls the QSYRUSRI API twice. That’s because we are using an API handling technique that we have aptly termed the “double-call technique.” The reason we employ the double-call technique is that we don’t really know what the length of the receiver variable should be. But this API, like many others, will tell you what the length needs to be. All you need to do is to shelve that macho instinct for a minute and ask for input.

And that is exactly what we do when we perform the first call to the API. We initially specify the size of the receiver variable as 8 bytes. In looking at the definition of this data structure, you will see that it is defined as two 10-digit integers, BytesRtn1 and BytesAvl1. After the first call to the API, BytesAvl1 will contain the number of bytes the API would return to the receiver variable if it could. So, we use the ALLOC op code and allocate the correct number of bytes for the receiver variable. We then call the API a second time using the returned information as the size of the receiver variable. This double-call technique is good to know when you’re dealing with many of the APIs that the system provides.

You might have noticed that we said the QSYUSRI API returns almost all of the information about a user profile. The missing piece of information is the password. (Wouldn’t you know it? Why would we need that?) So, the next thing the exit program must do is retrieve the password for the user profile.

You’re probably thinking, “I can get the password for a user profile? Wow! I can be king (or queen) of the computer! I can sign on as anybody and do anything! Way cool!” Well, we hate to burst your bubble, but it doesn’t work like that. There is an API that retrieves the password for a given user profile. That API is QSYRUPWD. The catch here is that it retrieves the encrypted form of the password. You cannot view it, so forget about being the king of all you survey. The only thing you can do with the encrypted form of the password is pass it along to the QSYSUPWD API, which will set the password for the user profile to the encrypted password. Also, you can only use the password on a user profile that has the same name as the one from which it was retrieved.

The program calls the RtvEncPwd procedure to retrieve the password of the user profile. This procedure accepts the user profile name, uses the double-call technique with the QSYRUPWD API, and then returns the data structure (with the encrypted password and user profile name) back to the caller of the procedure. We then concatenate the user profile information to the end of this password structure and write it to a remote data queue using the QSNDDTAQ API.

Primary to Backup: I Just Wanna Be with You

Let’s talk about data queues. A data queue is a straight line between two points. You put information in the queue on one end, and you can take that information off the queue on the other end. What’s especially appealing about data queues is that each end of the queue can be on a different computer! Your program doesn’t know or care. Take a moment to examine the following command to see how you go about creating a remote data queue:

CRTDTAQ +

DTAQ(QGPL/PASSUSER) +

TYPE(*DDM) +

MAXLEN(1000) +

SEQ(*KEYED) +

KEYLEN(4) +

RMTDTAQ(QGPL/PASSUSERRM) +

RMTLOCNAME(RMTNAME)

Did you notice the type parameter we used on the Create Data Queue (CRTDTAQ) command? We have specified a type of Distributed Data Management (DDM). As the name implies, the DDM value for the type parameter tells your AS/400 that the data queue being

created is really just a “pointer” to a data queue that will be located on a different system. When you create a DDM data queue, you must specify the name of the other computer using the Remote Location Name (RMTLOCNAME) parameter. In our example, we called the other computer RMTNAME.

Just as the RMTLOCNAME parameter told the system which computer the remote data queue resides on, the Remote Data Queue (RMTDTAQ) parameter tells the local machine the physical name and location of the data queue as it is defined on the remote system. In other words, this is where we specify the name of the data queue on the other computer that the DDM “pointer” will connect with. If you want this to work, you will need to create the standard (non-DDM) data queue on the other computer, and it must use the same name and location that you specified on the RMTDTAQ parameter.

That’s all there is to it on the primary computer. We have set up an exit point that will call the program whenever a user profile is created. We have also set up a remote data queue that the program will use to send information about the newly created user profile to the secondary machine. All that remains is to have a program take the information off the data queue and create a duplicate user profile on the secondary machine. Figure 2 shows most of the code that accomplishes this. You can find the complete program on the Midrange Computing Web site at www.midrangecomputing.com/mc.

The program on the remote system uses the QRCVDTAQ API to read the information from the data queue. It then formats a Create User Profile (CRTUSRPRF ) command and executes the command using the “system” procedure. If the program encounters an error, it uses the display op code to display the error number on the screen. If the program encounters no errors, it creates the user profile. All that remains is to set the correct password for it. We pull the encrypted password data structure off the data queue and use the QSYSUPWD API to set the correct password for the newly created user profile.

Bye, Bye, Bye

We have covered quite a few concepts and techniques in this article—remote data queues, exit points, and the API double-call technique for determining the proper length for a receiver variable. The combination of these functions will help you keep your user profiles in sync.

We would also like to apologize for the subtitles. Part of the price we pay for being parents of grade-school-aged daughters is feeling obligated to listen to “classics” sung by groups like *NSYNC. It really could have been worse: We could have made references to Britney Spears’ classic version of “I Can’t Get No Satisfaction.”

d Data S 1000
d DataQue S 10 inz('PASSUSERRM')
d DataQueLib S 10 inz('QGPL ')
d DataLength S 5 0 inz(1000)
D FormatName S 8 inz('USRI0300')
D InData S 38
d Key S 4 inz('0000')
d KeyLength S 3 0 inz(4)
D OI S 4 0
D ReceiveLen S 10i 0
D Receiver1 DS
D BytesRtn1 10i 0
D BytesAvl1 10i 0

c *entry Plist
c Parm InData

* Retrieve the user profile information
C Call 'QSYRUSRI'
C Parm Receiver1
C Parm 8 ReceiveLen
C Parm FormatName
C Parm UsrProfile
C Parm QusEc
c Alloc BytesAvl1 ReceivePtr
C Call 'QSYRUSRI'
C Parm QSYI0300
C Parm BytesAvl1 ReceiveLen
C Parm FormatName
C Parm UsrProfile
C Parm QusEc

* Retrieve the encrypted password data
c Eval PassWordDs = RtvEncPwd(UsrProfile)
c Eval DataLength = BytesAvl1 + 38
c Eval Data = PassWordDs + Qsyi0300

* Write the information to the DDM data queue
c CALL 'QSNDDTAQ'
C PARM DataQue
C PARM DataQueLib
C PARM DataLength
C PARM Data
C PARM KeyLength
C PARM Key

c Eval *inlr = *on

* procedure RtvEncPwd: Retrieve encrypted password for given user
P RtvEncPwd B export
d RtvEncPwd PI 38
d PmProfile 10 const

DQSYD0100 DS Based(ReceivePtr)
D* Qsy RUPWD UPWD0100
D QSYBRTN04 1 4B 0
D* Bytes Returned
D QSYBAVL04 5 8B 0
D* Bytes Available
D QSYPN06 9 18
D* Profile Name
D PassWord 19 38

D Receiver1 DS
D BytesRtn1 10i 0
D BytesAvl1 10i 0

DQUSEC DS 116 inz
D QUSBPRV 1 4B 0 inz(116)
D QUSBAVL 5 8B 0 inz(0)
D QUSEI 9 15
D QUSERVED 16 16
D QUSED01 17 116

D FormatName S 8 Inz('UPWD0100')
D InProfile S 10
D ReceiveLen S 10i 0

c Eval InProfile = PmProfile
C Call 'QSYRUPWD'
C Parm Receiver1
C Parm 8 ReceiveLen
C Parm FormatName
C Parm InProfile
C Parm QusEc
c Alloc BytesAvl1 ReceivePtr
C Call 'QSYRUPWD'
C Parm QsyD0100
C Parm BytesAvl1 ReceiveLen

C Parm FormatName
C Parm InProfile
C Parm QusEc

c Return QsyD0100
P RtvEncPwd E

Figure 1: This exit program will be called every time a new user is added to the primary system.

d System PR 10i 0 extproc('system')
d Cmd * value options(*string)
d CpfMsgId s 7 import('_EXCP_MSGID')
d FormatCmd PR 1000
d UsrProfile 10 const
d SetEncPwd PR
d PwdStruct 38

DPassWordDs DS 38
DReceiveDs DS 1000
d ProfData 39 1000

DQSYI0300 DS
D QSYUP03 9 18
D* User Profile
D QSYURITY00 519 519
D* Security

d DataQue S 10 inz('PASSUSERRM')
d DataQueLib S 10 inz('QGPL ')
d DataLength S 5 0 inz(1000)
d Key S 4 inz('0000')
d KeyLength S 3 0 inz(4)
d KeyOrder S 2 inz('EQ')
d SenderInf S 50
d SenderLen S 3 0 inz(50)
d WaitLength S 5 0 inz(-1)

* Read the data queue as entries arrive
c CALL 'QRCVDTAQ'
C PARM DataQue
C PARM DataQueLib
C PARM DataLength
C PARM ReceiveDs
C PARM WaitLength
C PARM KeyOrder
C PARM KeyLength
C PARM Key
C PARM SenderLen
C PARM SenderInf
c Movel ReceiveDs PassWordDs
c Movel ProfData Qsyi0300

* execute the command to create the user profile
c If System(FormatCmd(QsyUp03)) 0 * If procedure returned not zero, display the error msgid
c CpfMsgId dsply
c Else

* Set the password the same as in the original profile
c Callp SetEncPwd(PassWordDs)

c
c Endif
c
c eval *inlr = *on

P SetEncPwd B export
d SetEncPwd PI
d QSYSD0100 38

DQUSEC DS 116 inz
D QUSBPRV 1 4B 0 inz(116)
D QUSBAVL 5 8B 0 inz(0)
D QUSEI 9 15
D QUSERVED 16 16
D QUSED01 17 116

D FormatName S 8 Inz('UPWD0100')

C Call 'QSYSUPWD'
C Parm QsysD0100
C Parm FormatName
C Parm QusEc

c Return
P SetEncPwd E

Figure 2: This program duplicates a user profile onto a secondary machine.

Also Read

Practical Middleware: Starting the Journey

IBM i 7.2: The Carrot Versus the Stick

A Renaissance for Domino