Editor's note! This file has been converted from Word Perfect, and still needs some cleanup! (coming soon...) 101 (More Or Less) Moral Things To Do With HPSusan And The Other MPE/iX Predefined Variables In The Harem David L. Largent The Gilbert Companies, Inc. 700 South Council P.O. Box 1032 Muncie, Indiana 47308-1032 U.S.A. Telephone 317/284-4461 Facsimile 317/288-2079 Copyright 1993, 1995 David L. Largent Table of Contents 1 Introduction "Is this for me?". . . . . . . . . .1 2 What are MPE/iX predefined variables? . . . . . . .2 2.1 A brief comparison of JCWs and session-level variables.2 2.2 How can predefined variables help me? . . . . . . .3 2.3 I think I see how they could help me. So, how do I use a predefined variable?3 2.3.1 Predefined variable usage in jobs and/or sessions.3 2.3.1.1 The SHOWVAR command. . . . . . . . . . . .3 2.3.1.2 The SETVAR command.. . . . . . . . . . . .4 2.3.1.3 The INPUT command. . . . . . . . . . . . .5 2.3.1.4 The ERRCLEAR command.. . . . . . . . . . .7 2.3.1.5 The JCW mnemonics. . . . . . . . . . . . .7 2.3.2 Predefined variable usage in programs.. . . .8 2.3.2.1 The HPCIGETVAR intrinsic.. . . . . . . . .8 2.3.2.2 The HPCIPUTVAR intrinsic.. . . . . . . . 10 2.4 How about some examples?. . . . . . . . . . . . . 12 2.4.1 Batch job and session examples. . . . . . . 13 2.4.2 Programmatic examples.. . . . . . . . . . . 26 3 Closing thoughts "For a good time... check out HPSusan!"29 Acknowledgments. . . . . . . . . . . . . . . . . . . . . . 30 Bibliography . . . . . . . . . . . . . . . . . . . . . . . 31 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . 33 101 (More Or Less) Moral Things To Do With HPSusan And The Other MPE/iX Predefined Variables In The Harem David L. Largent The Gilbert Companies, Inc. 700 South Council P.O. Box 1032 Muncie, Indiana 47308-1032 U.S.A. Telephone 317/284-4461 Facsimile 317/288-2079 Copyright 1993, 1995 David L. Largent 1 Introduction "Is this for me?" Have you heard about HPSusan? Would a way to automate some of your procedures be helpful? Have you been looking for a way to make your job streams "smarter"? Would you like to develop a menu to select programs and commands from without using a programming language? Have you ever wanted to know exactly who was running a program, or how long they had been logged on? If you answered "yes" to any of these questions (and are using an MPE XL/iX system), and have never considered using the MPE/iX Predefined Variables, now is the time to do so. Add some spice to your life! On the following pages will be found answers to questions relating to MPE/iX Predefined Variables such as: What are they? How do they differ from JCWs? How can they help me? How are they used? If I ask them nicely, what will they tell me? To find the answers, we will examine what the predefined variables are and how they are used. We will examine a number of example command files, job streams, UDCs, and programs to see how and where MPE/iX predefined variables can be used and how they work. It is expected that you will find at least one idea (likely more) to put to use at your office. The information presented here is correct and up-to-date (to the best of my knowledge) and reflects the way predefined variables are used and work as of the B.40.00 release of MPE/iX (4.0). This paper is directed at new users of an HP 3000 MPE/iX computer system who have not yet explored the world of MPE/iX predefined variables. However, any user may find some tidbits to put in his or her "tool box" that will prove useful either now or in the future. So, for a good time... check out HPSusan! 2 What are MPE/iX predefined variables? A predefined variable is one way MPE/iX permits programs and commands to communicate with each other within a given job or session. Predefined variables are used at the operating system level and can take on virtually any value. Each predefined variable has a name and can be set and/or interrogated either by the operating system, MPE/iX system commands, or programs. 2.1 A brief comparison of JCWs and session-level variables. An extremely close relative (adopted child?) of the session-level variable is the JCW. JCWs are actually a subset of session-level variables, being restricted by values and naming conventions. The MPE V idea of providing users with operating system-level variables was expanded in MPE XL (and later in MPE/iX) to include data types other than numeric. MPE/iX session-level variables can retain data in Boolean form, 32-bit numeric form, and string form. JCWs are able to retain information in 16-bit numeric form only. These new variable types have made it possible for MPE/iX to provide a wealth of new information not readily available to the user previously. The information in the predefined variables range from the formatted time of day and job count, to the interactive state and CPU time used. Other variables are able to control the user's environment, such as changing the MPE/iX prompt and automatically logging the user off if there has been no activity within a given amount of time. In addition to the predefined variables, you may also create your own variables. A further discussion of JCWs and user-defined variables is outside the scope of this paper. As we progress through the material, however, there will be occasional references to user- defined variables. I strongly encourage you to learn all you can from other sources about the full range of variables. They will open up many doors you may not even know you want open! 2.2 How can predefined variables help me? Good question! Properly used, predefined variables will permit you to create "smarter" job streams. They can help to automate some of the decision making process in procedures. They can even help you catch errors before they become a problem! All of this is to say: predefined variables can help make the system more effective. Predefined variables can be checked to determine if certain events have occurred within MPE/iX. By testing predefined variables against specific values, the user can program conditional statements that take action(s) based on the results of the test. 2.3 OK, I think I see how they could help me. So, how do I use a predefined variable? First, some background information. Session-level variables are stored, along with JCWs, in the session's Variable Object Table. The Job Entry Table contains a pointer to this table, and is managed by MPE/iX. This table is shared by all processes in a given job or session. Two classes of variables exist: predefined and user-defined. In some ways, they are exactly the same in other ways, they are completely different. Predefined variables are named and assigned values by the system. Some of them may also be assigned values by the user. Both the system and the user may interrogate predefined variables. User-defined variables are named and assigned values solely by the user. MPE/iX never changes the value of or interrogates a user-defined variable. This class of variables will not be discussed at length in this paper. 2.3.1 Predefined variable usage in jobs and/or sessions. OK, so now you have a flavor of what the predefined variables are. But, how do you look at or set their values? For jobs or sessions, the answer involves the SHOWVAR, and SETVAR system commands. These commands correspond to the MPE/iX system commands SHOWJCW and SETJCW used for JCWs. (MPE/iX distinguishes between variables created by the SETJCW command and those created by the SETVAR command by way of an internal "flag".) Two additional commands, INPUT and ERRCLEAR, may also be used to manipulate predefined variables. 2.3.1.1 The SHOWVAR command. The SHOWVAR command displays the name(s) and current value(s) of one or more variables. Its syntax is: SHOWVAR [varname][,varname] ... [,varname] where varname is a valid variable name (any class). If a name is provided, then only the name(s) and value(s) for the provided variable(s) will be displayed. If a name is not provided, then all user-defined variables and JCWs and their values are displayed predefined variables are not displayed. You may use the standard wildcard characters to specify a set or range of variables. To display information for all JCWs and variables including predefined variables use @ as the varname. This command can be executed from a session, job, program, or in BREAK. It is BREAKable (it aborts execution of the command). For example, if you wish to see the current value of a specific predefined variable, you might type: SHOWVAR HPJOBNAME and the system would respond with: HPJOBNAME = DAVE 2.3.1.2 The SETVAR command. Big deal, so you can look at the value of a predefined variable. So what?!? OK, let me tell you how you can change or set the value of some of the predefined variables that is a little more productive. We need the SETVAR command to do this: {} SETVAR varname {, } expression {; } where varname is the name of a new or existing user-defined or predefined variable and expression represents a value, variable or JCW name, or an expression that will be evaluated and assigned to the specified variable. This command can be executed from a session, job, program, or in BREAK. Pressing BREAK has no effect on this command. A value in expression may be Boolean (true or false), integer (hexadecimal, octal, or decimal), or string (quoted). For a list and explanation of the operators allowed in expression, see the "Commands" reference manual. The JCW mnemonics (discussed later) are also allowed. When the SETVAR command is executed, it causes the MPE/iX Variable Object Table for your job or session to be scanned for the name of the specified variable. If the name is found, the variable is set to the value provided. If the name is not found, it is added to the table and then set to the value provided. Once a variable is created, it exists for the duration of that session or job, or until the DELETEVAR command or the HPCIDELETEVAR intrinsic is used to delete it. For example, to set the predefined variable called HPREDOSIZE to a value of 50, you could type: SETVAR HPREDOSIZE 50 And finally, if you want to create a user-defined variable that has a value representing two days from now, you could type: SETVAR TWODAYSFROMNOW HPDAY+2 This will take the current value from the predefined variable HPDAY and add two. Obviously you would need to follow the statement with an "IF" statement to handle the end of the week, but I think you probably get the idea. 2.3.1.3 The INPUT command. Another way of setting a value for a variable is by using the INPUT command. This command permits the interactive setting of a variable based on input from a user, and would most typically be used in a command file or UDC. Its syntax is: INPUT [NAME=]varname [;PROMPT=prompt] [;WAIT=seconds] where varname is the name of a new or existing user-defined or predefined variable which could be set with SETVAR. If the prompt parameter is specified, then prompt is displayed on the standard listing device ($STDLIST) before accepting input from the user. If delimiters (for example, comma or semicolon) are part of prompt, you must enclose the entire prompt string within quotation marks (" or '). The default is that no prompt is displayed. The seconds parameter specifies how many seconds MPE/iX will wait before aborting the command. The default is zero seconds, which means no time limit. This command can be executed from a session, job, program, or in BREAK. It is BREAKable (it aborts execution of the command without creating or modifying varname). When the INPUT command is executed, prompt is displayed (if specified) on $STDLIST before a value is read from the user. A read is then posted to the standard input device ($STDIN). This is a timed read if the seconds parameter is specified, and will terminate when either the user provides input, or the timed read expires. The INPUT command will terminate (and the session will be logged off) if the number of minutes specified in HPTIMEOUT passes. Once a value is provided by the user, the operation of the INPUT command is comparable to the SETVAR command. There are two exceptions, however: INPUT stores the user's value as a string (performing no expression evaluation), and INPUT's behavior when a timed read terminates. The INPUT command does not evaluate expressions, but simply stores the user's response as a character string. If you want the user's response to be treated as an expression and evaluated, you must follow the INPUT command with a SETVAR command as shown below. INPUT JUNK SETVAR JUNK !JUNK Note that if the expression involves character strings, and the user does not enclose them in quotes, the execution of the SETVAR command will result in an error. If the user responds to an INPUT command by pressing the return key (no other input), and the variable previously existed, the existing value is not changed. New variables are set to null ("") given this same situation. If a timed read expires before the user responds, values are treated the same as if the user had simply pressed the return key. In this situation however, a warning occurs and CIERROR is set to 9003. As an example, to prompt the user for a value for the predefined variable called HPREDOSIZE, you could use the following command in a UDC or command file: INPUT HPREDOSIZE,"Enter the new value for HPRedoSize",10 This will display the prompt "Enter the new value for HPRedoSize" on $STDLIST, and wait ten seconds for the user's response. If the user does not respond within ten seconds, the value of HPREDOSIZE will be left unchanged. Something to note is that if a colon (:) is read (as the first character) by the INPUT command at any level other than the root level of the command interpreter (CI), the following error message is returned: END OF FILE ON INPUT (CIERR900) 2.3.1.4 The ERRCLEAR command. A command that becomes useful as you develop command files, UDCs, and/or job stream files is ERRCLEAR. It initializes (zeros) all HP predefined error-related variables. Its syntax is rather simple: ERRCLEAR That's right there are no parameters! This command can be executed from a session or job. It is not BREAKable. Issuing the ERRCLEAR command is equivalent to issuing the following series of commands: SETVAR CIERROR OK SETVAR HPCIERR OK SETVAR HPCIERRCOL OK SETVAR HPFSERR OK You are still not feeling very productive with predefined variables yet, right!?! OK, here is the good stuff. Predefined variables are most often used to control the flow of batch jobs (they can also be used in command files, UDCs, and/or in sessions), taking various actions based on the results of previous steps. To do this, the IF/THEN, ELSE, ELSEIF, ENDIF, CONTINUE, ESCAPE, EXIT, RETURN, WHILE and ENDWHILE commands are used. For purposes of this paper, I am going to assume you either know how these MPE/iX system commands work or can easily acquire the knowledge as we look at examples. (Some examples will come later that should clear up some of your questions.) 2.3.1.5 The JCW mnemonics. A word or two about the four JCW mnemonics. These can be used to assign values to variables, or used in IF commands. They are "defined" in the table below. JCW Mnemonics Mnemonic Value OK Zero WARN 16,384 FATAL 32,768 SYSTEM 49,152 These are strictly mnemonics for specific values they cannot be used as variable or JCW names. You may use a combination of a mnemonic and a number to indicate a value between two mnemonics. If you specify: FATAL32 for example, an implied addition takes place (32,768 + 32) and the value would be 32,800. The "+" and "-" option can also be used with mnemonics. For example: FATAL - 768 will result in a value of 32,000. 2.3.2 Predefined variable usage in programs. Now, for you programmer-type people, we will look at how to interrogate and set predefined variables from within a program. The intrinsics HPCIGETVAR and HPCIPUTVAR will be utilized. These correspond to the MPE/iX CI commands SHOWVAR and SETVAR used on standard variables. (Actually, these variable intrinsics may be used to set and display JCWs as well.) MPE/iX distinguishes between variables created by the PUTJCW intrinsic and those created by the HPCIPUTVAR intrinsic by way of an internal "flag". My examples are based on COBOL II/XL usage; however, I will try to provide information in a general way. 2.3.2.1 The HPCIGETVAR intrinsic. The programmatic equivalent to the SHOWVAR command is the HPCIGETVAR intrinsic. Its syntax (in COBOL II/XL format) is: CALL INTRINSIC "HPCIGETVAR" USING varname, status [, itemnum, item] [ ... ] where varname is an alphanumeric variable (character array) containing the name of the variable (or JCW) to be found, and status is a signed 32-bit integer variable to which a value denoting the execution status of the intrinsic is returned. The varname parameter may contain up to 255 alphanumeric characters, starting with a letter (or the underscore ( _ ) character) and ending with a non-alphanumeric character, such as a blank. (The underscore is not a valid delimiter since it is a valid variable name character.) The name is not case sensitive. If the requested variable is found in the session's Variable Object Table, its value is returned to the program in an item parameter; if not found, no change is made to this parameter. The status parameter will be returned with one of a number of possible values. If no errors or warnings are encountered, all 32 bits of the status parameter are set to zero. If an error or warning is encountered, the first 16 bits (0-15) provide an error or warning number. Error conditions are represented by negative values; warnings are represented by positive values. In an error or warning situation, the second set of 16 bits (16-31) will be set to 166 which is the subsystem identifier for HPCIGETVAR. Shown below is a partial list of possible error numbers that may be returned. This list was obtained from an old edition of the MPE XL Intrinsics Reference Manual. The current edition does not specifically list the errors (nor are they documented anywhere else!). I am sure the list is neither complete nor up to date. A Few Status Parameter Values for the HPCIGETVAR Intrinsic (First Word Only) Status Value Meaning or Result 0 Successful execution: The value of varname has been retrieved from the session's Variable Object Table. -8106 Error: Varname was not found in the session's Variable Object Table. -8110 Error: Varname is not valid. -8156 Error: Varname is longer than 255 characters. The itemnum parameter is an unsigned 32-bit integer variable in which you specify the item you want retrieved. See below for possible values. The item parameter varies in type (see below), and is used to return the requested information or value. The HPCIGETVAR intrinsic can be used to obtain the value and/or attribute of any of the classes of variables or JCWs. You may specify up to six itemnum/item pairs. Item Number/Item Parameter Values for the HPCIGETVAR Intrinsic Item Number Item Type Description or Meaning 0 (not applicable) Itemnum/item pair ignored. 1 32-bit signed integer Integer value of varname. Zero is returned if varname is not an integer variable. 2 Alphanumeric (character array) String value of varname. An ASCII zero is returned if varname is not a string variable. Item pair 10 should also be used with the pair. 3 32-bit signed integer Boolean value of varname, where true = one, and false = zero. Zero is returned if varname is not a boolean variable. 10 32-bit signed integer Length of array (character string) passed to hold varname's string value. If length is passed and an array is not, an error occurs. The default length is 255. Used in conjunction with item pair 2. 11 32-bit signed integer Actual length (in bytes) of varname's string value. 12 32-bit signed integer Value of varname: nonzero if varname is recursively dereferenced; zero for a level-1 value. Default value is one (nonzero). 13 32-bit signed integer Type of variable, where integer = one, string = two, and boolean = three. To accomplish the same task in RPG/XL, use the INTR operation to call HPCIGETVAR. If you are not familiar with how to do this, you may want to reference HP 3000 Application Note # 94: RPG/XL Intrinsic Interface dated January 15, 1992 (document part number 5960-8223). 2.3.2.2 The HPCIPUTVAR intrinsic. The SETVAR command's programmatic equivalent is the HPCIPUTVAR intrinsic. Its syntax (in COBOL II/XL format) is: CALL INTRINSIC "HPCIPUTVAR" USING varname, status [, itemnum, item] [ ... ] where varname is an alphanumeric variable (character array) containing the name of the variable (or JCW) to be created or changed, and status is a signed 32-bit integer variable to which a value denoting the execution status of the intrinsic is returned. The varname parameter may contain up to 255 alphanumeric characters, starting with a letter (or the underscore ( _ ) character) and ending with a non-alphanumeric character, such as a blank. (The underscore is not a valid delimiter since it is a valid variable name character.) The name is not case sensitive. If the requested variable (or JCW) is found in the session's Variable Object Table, its value is changed to the value provided in an item parameter; if not found, an entry is created and then is assigned the specified value. The status parameter will be returned with one of a number of possible values. If no errors or warnings are encountered, all 32 bits of the status parameter are set to zero. If an error or warning is encountered, the first 16 bits (0-15) provide an error or warning number. Error conditions are represented by negative values; warnings are represented by positive values. In an error or warning situation, the second set of 16 bits (16-31) will be set to 166 which is the subsystem identifier for HPCIPUTVAR. Shown below is a partial list of possible error numbers that may be returned. This list was obtained from an old edition of the MPE XL Intrinsics Reference Manual. The current edition does not specifically list the errors (nor are they documented anywhere else!). I am sure the list is neither complete nor up to date. A Few Status Parameter Values for the HPCIPUTVAR Intrinsic (First Word Only) Status Value Meaning or Result 0 Successful execution: varname has been entered in the session's Variable Object Table. -8110 Error: Varname is not valid. -8156 Error: Varname is longer than 255 characters. The itemnum parameter is an unsigned 32-bit integer variable in which you specify the item you want set. See below for possible values. The item parameter varies in type (see below), and is used to specify the value for varname and/or other information. The HPCIPUTVAR intrinsic can be used to set the value of any of the user-defined variables or JCWs, and the user-writable variables or JCWs. You may specify up to three itemnum/item pairs. Item Number/Item Parameter Values for the HPCIPUTVAR Intrinsic Item Number Item Type Description or Meaning 0 (not applicable) Itemnum/item pair ignored. 1 32-bit signed integer Integer value to be assigned to varname. No other pairs are required, and will cause an error if present. 2 Alphanumeric (character array) String value to be assigned to varname. Must also provide item pair number 11. 3 32-bit signed integer Boolean value to be assigned to varname, where true = nonzero, and false = zero. No other pairs are required, and will cause an error if present. 11 32-bit signed integer Actual length (in bytes) of string to be assigned to varname. Used in conjunction with item pair 2. 13 32-bit signed integer Item two's value will store as a string value if this item has a nonzero value. If this item's value is zero, Boolean and integer interpretation of item two's value will be attempted first. To accomplish the same task in RPG/XL, use the INTR operation to call HPCIPUTVAR. If you are not familiar with how to do this, you may want to reference HP 3000 Application Note # 94: RPG/XL Intrinsic Interface dated January 15, 1992 (document part number 5960-8223). 2.4 How about some examples? Good idea! First, we will look at some examples in batch jobs and sessions, then we will take a look at a couple example programs that use predefined variables. As predefined variables are presented in an example for the first time, we will take a look at what it can tell us. In later examples, you will be on your own to remember what it does you know, the old "building block" theory of teaching/learning. So sharpen your pencils; here we go... 2.4.1 Batch job and session examples. Here is a command file that will tell a user virtually everything they could ever want to know about their logon. Comment File: ME Comment Comment Set enhancement variables: I = Inverse U = Underline SetVar ENHOFF chr(27)+"&d@" SetVar ION chr(27)+"&dB" SetVar UON chr(27)+"&dD" Echo Echo !"ION" USER INFORMATION & STATUS !ENHOFF Echo Echo !"UON"User Identification:!ENHOFF Echo Session/Job #: !HPJOBTYPE!HPJOBNUM Echo Job/Session Name: !HPJOBNAME& ![rpt(" ",8-len("!HPJOBNAME"))] User: !HPUSER Echo Current Group: !HPGROUP& ![rpt(" ",8-len("!HPGROUP"))] Account: !HPACCOUNT Echo Home Group: !HPHGROUP Echo Search Path: !HPPATH Echo LDev In/Out #: !HPLDEVIN/!HPLDEVLIST Echo DTC Port ID #: !HPDTCPORTID Echo Echo !"UON"Dates & Times:!ENHOFF Echo Current: !HPDATEF at !HPTIMEF Echo Logged on: !HPINTRODATE at !HPINTROTIME SetVar ME_HOURS !HPCONNMINS/60 Echo Time since logon: !ME_HOURS hours & ![!HPCONNMINS - (!ME_HOURS * 60)] minutes Echo CPU since logon: !HPCPUSECS seconds Echo SetVar HPMSGFENCE 2 Input ME_DUMMY, " Press RETURN to see more information.",20 SetVar HPMSGFENCE 0 Echo Echo !"UON"Status Information:!ENHOFF Echo Redo Stack Size: !HPREDOSIZE commands Echo Command Number: !HPCMDNUM Echo Nested Commands: !HPUSERCMDEPTH Echo CI Level number: !HPCIDEPTH Echo Command Time Out: !HPTIMEOUT minutes If HPTYPEAHEAD SetVar ME_YES_NO "Yes" Else SetVar ME_YES_NO "No" EndIf Echo Type Ahead On? !ME_YES_NO If HPQUIET SetVar ME_YES_NO "Yes" Else SetVar ME_YES_NO "No" EndIf Echo Quiet Mode On? !ME_YES_NO .....(continued)..... .....(continued)..... If HPINBREAK SetVar ME_YES_NO "Yes" Else SetVar ME_YES_NO "No" EndIf Echo In Break Mode? !ME_YES_NO Echo Echo !"UON"Capabilities:!ENHOFF Echo Account: !HPACCTCAPF Echo Group: !HPGROUPCAPF Echo User: !HPUSERCAPF DeleteVar ME_@ As a command file, this is pretty straightforward. Just a bunch of ECHOs, a few IFs and SETVARs, and an INPUT and DELETEVAR thrown in for good measure. Notice the INPUT will time out after 20 seconds, so if the user does not respond right away, it will move forward automatically. So what do all of those predefined variables mean? Starting at the top of the command file and working our way down, let's take a look. HPJOBTYPE provides a value of "S" if the logon is a session, and "J" if a job. HPJOBNUM is the job/session number. The job or session name is in HPJOBNAME. You'll find the user, group and account stored in HPUSER, HPGROUP and HPACCOUNT respectively, while HPHGROUP holds the user's home group. The search path is defined in HPPATH. The logical device number (LDEV #) for $STDIN and $STDLIST are provided in HPLDEVIN and HPLDEVLIST. And finally, HPDTCPORTID holds the port ID of the DTC the user's terminal is connected to. OK. Take a big breath; here we go again. HPDATEF and HPTIMEF provide the current formatted date and time. HPINTRODATE and HPINTROTIME will tell you (formatted) the date and time the user logged on. If you want to know how many minutes have passed since you logged on, check HPCONNMINS. There is also HPCPUSECS that provides the number of seconds the CPU has been doing work for your session. Hang on, we still have a few more to go! If you are not familiar with the LISTREDO command, you owe it to yourself to start looking. HPREDOSIZE is the variable that controls how big your redo stack is. HPCMDNUM tells you the current command number (i.e. how many commands you have executed since you logged on). HPUSERCMDEPTH provides the answer to the question "How deep am I in nested command files and UDCs?". The number of nested CIs is provided in HPCIDEPTH. The number of minutes allowed for CI reads before it logs you off is controlled by HPTIMEOUT. HPTYPEAHEAD is set to TRUE if the type ahead feature is enabled for your session (this is separate and distinct from Reflection's type ahead). If your session is not accepting messages via the TELL command, HPQUIET will be set to TRUE. And almost lastly, if your session is "in break", HPINBREAK will have a value of TRUE. The account, group and user capabilities are stored in HPACCTCAPF, HPGROUPCAPF and HPUSERCAPF. These are formatted (i.e. the bits are translated into letters). Well, if you survived that, you can handle any of the others this one was by far the highest concentration of predefined variables in one example. Here is a counterpart for the ME command file that displays the system's information and status. Comment File: SYSSTAT Comment Set enhancement variables: Comment I = Inverse U = Underline SetVar ENHOFF chr(27)+"&d@" SetVar ION chr(27)+"&dB" SetVar UON chr(27)+"&dD" Echo Echo !"ION" SYSTEM INFORMATION & STATUS !ENHOFF Echo Echo !"UON"System Identification:!ENHOFF Echo System Name: !HPSYSNAME Echo CPU Model: !HPCPUNAME Echo HP System ID#: !HPSUSAN Echo MPE Version: !HPVERSION Echo Echo !"UON"Session & Job Counts:!ENHOFF Echo Executing Jobs & Sessions: !HPEXECJOBS Echo Sessions: !HPSESCOUNT Echo Jobs: !HPJOBCOUNT Echo Non-executing Jobs: Echo Suspended: !HPSUSPJOBS Echo Waiting: !HPWAITJOBS Echo Scheduled: !HPSCHEDJOBS Echo Total Users: !HPUSERCOUNT Echo Echo !"UON"Limits:!ENHOFF Echo Current Limits: Sessions: !HPSESLIMIT Jobs: !HPJOBLIMIT Echo Max Users Allowed: !HPUSERLIMIT Echo Job Fence: !HPJOBFENCE Echo Output Fence: !HPOUTFENCE It is just a bunch of ECHO commands to display the information, but it does give us a chance to talk about what each of the predefined variables do. So, here we go. HPSYSNAME will contain what ever name you have assigned to your system, and (via SETVAR) placed into the variable. HPCPUNAME, on the other hand, is the name of the computer model (for example, SERIES 922LX). The MPE/iX operating system version is stored in HPVERSION. If you want to know the number of executing jobs and sessions, look at HPEXECJOBS. If you want a breakdown, HPSESCOUNT and HPJOBCOUNT have your answers. The number of currently suspended, waiting, and scheduled jobs can be found in HPSUSPJOBS, HPWAITJOBS, and HPSCHEDJOBS. HPUSERCOUNT is the number of users (defined as non-OPERATOR.SYS) currently on the system. And finally some limits. HPSESLIMIT and HPJOBLIMIT provide the current settings of the session and job limits. The maximum number of users allowed on the system is stored in HPUSERLIMIT. The job and out fences can be found in HPJOBFENCE and HPOUTFENCE. If you were following along in the example, you will have noticed I skipped over one of the predefined variables. HPSUSAN. Ah yes, we finally get to talk about the mysterious "woman" from the title of the paper! HPSUSAN is an "electronic serial number" which, according to HP, no other system has. (Via comments from the grapevine, I think there are a few isolated exceptions that turn up from time to time however.) The name is actually an acronym for the words "System Unique Serially Assigned Number". So what purpose does it serve? About the same as any serial number does. Software companies have found they can use HPSUSAN as a way to tie a particular copy of their software to a given machine, thus controlling software piracy. They simply request your HPSUSAN and include that in some validation logic in their program that prohibits the running of their software if the HPSUSAN from the system does not match the value in the software. The following is a modified version of the job stream we use to do our system back ups. !Job BACKUP,OPERATOR.SYS;Pri=CS !Comment****************************************************** !Comment BACKUPJ * !Comment This job stream backs-up the system (using * !Comment STORE) onto magnetic tape. A free disk space * !Comment table is produced, as well as a summary of * !Comment computer use by group by account. * !Comment****************************************************** !DiscFree A !DiscFree C !Report !SetVar MONDAY 2 !SetVar THURSDAY MONDAY + 3 !SetVar ION chr(27)+"&dB" !SetVar ENHOFF chr(27)+"&d@" !If HPDAY = MONDAY or HPDAY = THURSDAY then ! SetVar BACKUP_IS_FULL TRUE !ElseIf finfo("FULLDATE","EXISTS") then ! SetVar BACKUP_IS_FULL FALSE !Else ! Comment To force a full back up on other days, simply ! Comment PURGE FULLDATE.OPER.SYS. ! TellOp ! TellOp !"ION" Full back up date file (FULLDATE.OPER.SYS) !ENHOFF ! TellOp !"ION" is missing. Performing a Full back up !ENHOFF ! TellOp !"ION" instead of the usual Partial back up. !ENHOFF ! SetVar BACKUP_IS_FULL TRUE !EndIf !If BACKUP_IS_FULL then ! SetVar BACKUP_DATE_F "" !Else ! SetVar BACKUP_DATE_I finfo("FULLDATE","INTCREATED") ! SetVar BACKUP_DATE_C "!BACKUP_DATE_I" ! SetVar BACKUP_DATE str("!BACKUP_DATE_C",5,2)+"/"+& ! str("!BACKUP_DATE_C",7,2)+"/"+& ! str("!BACKUP_DATE_C",3,2) ! SetVar BACKUP_DATE_F ";DATE>="+"!BACKUP_DATE" !EndIf .....(continued)..... .....(continued)..... !SetVar BACKUP_FILE_SET "@.@.SYS,@.@.@-@.@.SYS" !TellOp !If BACKUP_IS_FULL then ! TellOp Today's back up will be a Full back up. !Else ! TellOp Today's back up will copy all files modified ! TellOp on or after !BACKUP_DATE. !EndIf !TellOp !TellOp Please mount a tape for the back up. !If finfo("LASTBACK","EXISTS") and & ! finfo("LASTBACK","CREATED") = HPDATEF then ! TellOp!"ION" It appears that a back up has already been !ENHOFF ! TellOp!"ION" performed today. Abort the job if you do !ENHOFF ! TellOp!"ION" not want it done a second time. !ENHOFF ! TellOp !EndIf !File BACKUPT;dev=TAPE !Store !BACKUP_FILE_SET;*BACKUPT;Directory;Show& !!BACKUP_DATE_F;Progress=5 !If BACKUP_IS_FULL and HPDAY <> THURSDAY then ! If finfo("FULLDATE","EXISTS") then ! Purge FULLDATE ! EndIf ! Build FULLDATE !EndIf !If finfo("LASTBACK","EXISTS") then ! Purge LASTBACK !EndIf !Build LASTBACK !TellOp******************************************************* !TellOp The BACKUPJ job stream is done. !TellOp !"ION"Don't forget to set the limits back up.!ENHOFF !TellOp******************************************************* !EOJ Notice the creation of variables MONDAY and THURSDAY. They are not necessary, but make the IF commands read a little nicer. Also, ION and ENHOFF are set up to use when the inverse video enhancement is to be turned on and off. For us, full back ups should be performed on Monday and Thursday; otherwise, a partial back up is done. Which to do is decided by checking HPDAY, which is a number from one to seven, where one is Sunday. The creation date of file LASTBACK is the last time a back up was performed. The creation date of file FULLDATE is the last time a full back up was performed. Both of these files are built, but contain no data, and as such, do not require any disk space. Their sole purpose in life is to provide the last date an event occurred by way of their creation date. There are around forty MPE/iX expression evaluator functions that do and/or tell you virtually anything you want. Used in this job stream are two of them. finfo(...,"EXISTS") returns a value of TRUE if the file exists, and FALSE if the file does not. finfo(...,"INTCREATED") returns the creation date of the file as an integer in the form yyyymmdd. finfo(...,"CREATED") returns the formatted creation date of the file. str(...) extracts individual characters from a character string variable. You say you're looking for a way to implement a menu system that can shield the user from the MPE/iX prompt (and vice versa)? The following command file will give you a good start. Parm WHICHCHOICE = Warn Option NoList,NoBreak Comment File: MENU Comment Author: David L. Largent Comment Date: 07/06/93 SetVar HPMSGFENCE 2 SetVar HPAUTOCONT TRUE SetVar CHOICE Warn + 1 SetVar CHOICE !WHICHCHOICE SetVar RESPONSE " " SetVar ESC chr(27) SetVar HPMSGFENCE 0 While CHOICE <> 0 Do SetVar HPMSGFENCE 2 If CHOICE = Warn then Echo Options for !HPUSER.!HPACCOUNT are: Echo 1 - Run Report A Echo 2 - Run Report B Echo 3 - Show System Information & Status Echo 4 - Show Information About Your Logon Echo 5 - Show Printer Output Pending From Your Logon Echo 6 - Access the E-Mail System Echo 7 - Access the Command Prompt Echo 0 - Logoff the System SetVar RESPONSE " " SetVar MINUTES_PASSED 0 SetVar HPMSGFENCE 2 While RESPONSE = " " Comment The following mess places the date and time inside of parenthesis Comment in front of the prompt. It also causes the prompt to be displayed Comment over top of the last one. Input RESPONSE, "!["!"ESC"A!"ESC"M" + & "(" + rpt("0",2-len("!HPMONTH")) + "!HPMONTH/" + & rpt("0",2-len("!HPDATE")) + "!HPDATE/!HPYEAR " + & rpt("0",2-len("!HPHOUR")) + "!HPHOUR:" + & rpt("0",2-len("!HPMINUTE")) + "!HPMINUTE) " + & "Type the number of your selection !HPJOBNAME: "]",60 If HPCIERR = -9003 then SetVar MINUTES_PASSED MINUTES_PASSED + 1 If MINUTES_PASSED > HPTIMEOUT Echo There has been no response from you during the last & !HPTIMEOUT minutes !HPJOBNAME. Echo You will therefore be automatically logged off. SetVar RESPONSE "0" EndIf EndIf EndWhile .....(continued)..... .....(continued)..... SetVar HPMSGFENCE 2 If numeric(RESPONSE) then SetVar CHOICE !RESPONSE Else SetVar CHOICE Warn EndIf EndIf SetVar HPMSGFENCE 0 If CHOICE = 1 then Run Prog1 ElseIf CHOICE = 2 then Run Prog2 ElseIf CHOICE = 3 then Xeq SYSSTAT Echo Input DUMMY, "Press RETURN to display the Menu." ElseIf CHOICE = 4 then Xeq ME Echo Input DUMMY, "Press RETURN to display the Menu." ElseIf CHOICE = 5 then ListSpf ;Detail Echo Input DUMMY, "Press RETURN to display the Menu." ElseIf CHOICE = 6 then Xeq MAIL ElseIf CHOICE = 7 then Echo Echo Type EXIT to return to the Menu when done. Echo SetVar OLDPROMPT HPPROMPT SetVar HPPROMPT "EXIT to return to Menu:" CI.PUB.SYS SetVar HPPROMPT OLDPROMPT ElseIf CHOICE <> 0 Echo If RESPONSE = " " then Echo Your selection of "!WHICHCHOICE" is not a valid response. Else Echo Your selection of "!RESPONSE" is not a valid response. EndIf Echo Please re-enter your selection. EndIf If CHOICE <> 0 then SetVar CHOICE Warn EndIf EndWhile Bye Since the command file has a parameter, the user may indicate which function to perform without the necessity of displaying the menu the first time. If no parameter value is provided, the menu will be displayed, and the user prompted for their selection. Unless the user has chosen to leave the menu, the variable CHOICE is set to the mnemonic WARN at the end of the command file to force the menu to be displayed. NUMERIC(...) is used to determine if the user typed anything other than digits; this will be false if they did. Also note the provision for temporarily exiting to the MPE/iX command interpreter. From here the user may enter MPE/iX commands, but may not run a program unless they have the process handling (PH) capability. We have a few new predefined variables to talk about, so let's get started. The HPMSGFENCE variable is used to control error messages printed by the CI. If this variable is set to zero, the CI displays all errors and warnings as usual. However, if it is set to one, the CI will only display error messages, and if set to two, all CI messages are suppressed. By setting HPAUTOCONT to TRUE, you can avoid the need to place CONTINUE statements throughout. It is like having a CONTINUE in front of every command. HPMONTH, HPDATE, and HPYEAR provide the month number, day of month, and year respectively. The current hour and minute is provided by HPHOUR and HPMINUTE. HPCIERR contains the last CI error or warning number from your job or session. HPPROMPT is used here to provide a reminder of how they get back to the menu from the CI. You can use virtually any character string for the prompt including any of the predefined variables! The inside WHILE loop is an interesting feature. It contains a timed INPUT command that will display the current date and time in front of the prompt. Because of the timed read and the loop, the time will stay up-to-date. The escape sequence will delete the last line before displaying it again. Also note, if the user does not respond to the command file before the number of minutes specified in HPTIMEOUT has passed, the user will automatically be logged off the system. If you want to make the menu easier to use, consider loading the function keys with the menu selections. The user can then simply press a function key to make a selection, rather than typing a number and pressing the return key. Hey system managers; do you have things you want to be performed every time a user logs on? Are there varying activities for certain accounts or users that should always be done? You can provide this functionality with logon UDCs. You say UDCs are a bit cumbersome, and have to be uncatalogued/catalogued every time you want to make a change? Well there is an alternative sort of. The solution still involves a logon UDC, but it does address the cumbersome issue. I have seen this approach before, but the reference I found when developing this paper appeared in the "Users Forum" column of the September 1992 issue of Interact magazine. I have made a few refinements, and present it here for your consideration. SYSLOGON Option LOGON,NOLIST,NOBREAK Comment File: SYSUDC Comment Source: INTERACT 9/92 Page 12 Comment System level logon commands. If finfo("LOGONCMD.PUB.SYS","EXISTS") then Xeq LOGONCMD.PUB.SYS EndIf Comment Account level logon commands. If HPACCOUNT <> "SYS" and finfo("LOGONCMD.PUB","EXISTS") then Xeq LOGONCMD.PUB EndIf Comment User level logon commands. If HPHGROUP <> "PUB" and finfo("LOGONCMD.!HPHGROUP","EXISTS") then Xeq LOGONCMD.!HPHGROUP EndIf ** Command files do not provide a LOGON option, so if we want this functionality, we must use at least one UDC, and the above UDC is it. It does nothing except execute three command files: one each to imitate a system level, account level, and user level logon UDC. Each of the command files then contain all of the programs that need to be run, and settings that need to be made, for each level at logon time. To change what happens at a given level, simply change the appropriate command file and you are done. This can even be done while people are logged on. You will note the UDC confirms the existence of the command file before it tries to execute it, so you are not forced to have a file at every level for every account or user. Also note that what command file(s) actually get executed depends on the logon group and account, since it is based on the logon account and user name. Here is a sample of what the LOGONCMD.PUB.SYS file might look like. Comment File: LOGONCMD.PUB.SYS Comment Original Source: INTERACT 9/92 Page 12 SetVar HPSYSNAME "The Gilbert Companies, Inc. - Muncie" If "!HPHGROUP" <> "PUB" then SetVar HPPATH "PUB,PUB.SYS,COMMAND.SYS,!HPHGROUP" Else SetVar HPPATH "PUB,PUB.SYS,COMMAND.SYS" EndIf Echo Echo The following file equations have been set: Option List File LP;Dev=LP File T;Dev=TAPE Nothing fancy here; just a list of commands to be performed for every user that logs onto the system. If you have a logon security system, commands to initiate it would be placed here. You can create a similar command file for each account on your system; each user too! You can effectively keep the user from the CI prompt, thus providing some level of security for free, by having one of these start another command file or a program to place the user into their application. The application must then be followed with a BYE command to log the user off. Do not forget to use the NOBREAK option to disable the BREAK key. Have you ever been frustrated with yourself when you logged off because you typed EXIT at the CI prompt and did not realize you were running your first level of the CI? Another problem you may have is forgetting to return the console to its rightful place before logging off. Well, here are a couple of solutions to those problems. These will be most effective as system-level UDCs. In fact, they must be set up as UDCs. If you try to use command files for them, they will never be performed because UDCs and MPE/iX commands are performed before command files unless you use the XEQ command. Exit Option NoList Comment File: EXITUDC Comment Original Source: INTERACT 3/92 Page 12 Comment This UDC MUST be defined above the BYE UDC. ErrClear If HPINTERACTIVE and HPCIDEPTH = 1 SetVar ANSWER "N" SetVar HPMSGFENCE 2 Input ANSWER, " Do you really want to logoff? (N/Y)", 15 SetVar HPMSGFENCE 0 If HPCIERR = -9003 then Echo Timed 15-second read expired. A "no" answer was assumed. ElseIf ups("!ANSWER") = "Y" or ups("!ANSWER") = "YES" then Comment Perform BYE UDC... Bye EndIf DeleteVar ANSWER Else Exit EndIf ** Bye Option NoList If HPLDEVIN <> 20 and HPLDEVIN = HPCONSOLE then Console 20 EndIf Bye ** Notice the use of the INPUT command to get a response from the user in the EXIT UDC. HPINTERACTIVE has a value of TRUE if the logon is interactive (i.e. a session). In case you are not aware, you can run the CI from within the CI from within the CI, etc.. To back up to the previous copy of the CI, you use the EXIT command. If EXIT is used at the first level, however, it performs as if you had typed BYE. This UDC gives you a second chance to change your mind before MPE/iX logs you off. The UPS function performs an upshift of the character string given it. The BYE UDC (which is also referenced in the EXIT UDC) provides the check for the console. By looking at HPLDEVIN and comparing that against HPCONSOLE, which contains the LDEV number of the system console, the UDC is able to determine if it needs to transfer the console back to its normal home before logging you off. Again, please note that these must both be defined as UDCs, and that the definition of the BYE UDC must occur after the EXIT UDC, so that when BYE is referenced in EXIT, the BYE UDC will be performed, and not the BYE command. Here is a fun little command file (actually it has some size to it). Have you ever wanted a stopwatch functionality on the HP 3000? If yes, this command file is for you! Take some time to look. parm action="none" comment File: SW - A Stop Watch for MPE/XL Command Interpreter comment Source: INTEREX CSLXL comment comment This command file simply reports elapsed time from one point comment to another. The "action" parameter is used to control the comment stop watch functions. comment comment START: Start the stop watch comment REPORT: Shows the elapsed time since "start" comment RESET: Zeros the stop watch to setup for a new timing run comment comment Author: Guy Smith comment Company: Circuit City Stores, Inc. comment Last rev: 07/17/91 comment Warning! This command file assumes MPE/XL 2.2 or better. comment***************************************************************** SetVar action ups("!action") if action="START" then if bound(SW_START) then comment ******************************************************* comment Existence of SW_START indicates error. Let user know echo StopWatch has already been started. Use RESET first to echo zero timer, then START to begin timing else comment ******************************************************* comment StopWatch is not running, so start-it-up echo StopWatch has started at !HPTIMEF SetVar SW_START HPCONNSECS endif elseif action="REPORT" then if bound(SW_START) then comment ******************************************************* comment SW_START exists, so it's OK to calculate elapsed time comment First, get current connect seconds before processing SetVar SW_STOP HPCONNSECS SetVar SW_DELTA SW_STOP-SW_START comment ******************************************************* comment Now calculate elapsed days, hours, minutes, seconds SetVar SW_DAYS SW_DELTA/86400 SetVar SW_HOURS (SW_DELTA-SW_DAYS*86400)/3600 SetVar SW_MINUTES (SW_DELTA-SW_DAYS*86400-SW_HOURS*3600)/60 SetVar SW_SECONDS (SW_DELTA-SW_DAYS*86400-SW_HOURS*3600- & SW_MINUTES*60) echo StopWatch elapsed time Day: !SW_DAYS echo Hours: !SW_HOURS echo Minutes: !SW_MINUTES echo Seconds: !SW_SECONDS else comment ******************************************************* comment Tried to STOP without STARTING, so tell 'em echo echo StopWatch must be STARTed in order to report an elapsed echo time. endif elseif action="RESET" then if bound(SW_START) then DeleteVar SW_@ endif echo StopWatch has been reset .....(continued)..... .....(continued)..... else comment User has specified an unknown action echo echo StopWatch can't figure out what you want. if action="NONE" then echo You failed to tell me to take any kind of action. else echo Action !action is unknown. endif echo I won't do anything. endif Guy Smith has done a nice job on this one. I have not found much to change in it. The use of the command file and how it works is fairly straightforward. Take a look at Guy's comments in the command file they pretty well spell out what is going on. The only new predefined variable is HPCONNSECS which provides the number of elapsed seconds since your log on time. OK operator-type people, how many of you have ever needed to raise the job limit so a job could start running, but then lowered it right after it started? I thought so. Well here is a little command file you might find helpful. I found this in the "Questions & Answers" column of the March 1992 issue of Interact magazine. Parm JDELTA = 0 Comment File: JOBLIMUP Comment Source: INTERACT 3/92 Page 12 Limit ![!HPJOBLIMIT+!JDELTA] Pause 5 Limit ![!HPJOBLIMIT-!JDELTA] There is nothing real sophisticated here; we simply take the current job limit, add a value to it, wait five seconds, and then set the job limit back to the original value. In case you are curious, yes you can give it a negative value for JDELTA. It temporarily LOWERS the limit and then raises it I am not sure why you would want to do that, but it does work. Here is a little command file to help with the CONSOLE command. The "Questions & Answers" column of the March 1992 issue of Interact magazine gave me the foundation, but I've elaborated on the original a bit. Parm LDEV=" " Comment File: CONS Comment Original Source: INTERACT 3/92 Page 12 If ups("!LDEV") = "ME" then If HPLDEVIN = HPCONSOLE then If HPJOBNAME = "" Echo You already have the console !HPUSER. Else Echo You already have the console !HPJOBNAME. EndIf Else Console !HPLDEVIN EndIf Else Console !LDEV EndIf There are three modes of operation for this command file. If you do not provide a parameter, it simply responds with the LDEV number of the location of the console. If you specify an LDEV number, it will attempt to move the console to that device. Lastly, if you provide the word "me", it will attempt to relocate the console to your terminal. This provides a way of getting the console with out needing to know the LDEV number of the terminal you are logged on. To accomplish all of this, it simply works through a series of IF commands. A simple addition to the system-level logon UDC (or the command file executed from it) makes use of the predefined variable HPDAY easier. By including this functionality at the system level, the following seven variables will always be available for use in IF commands. SetVar Sunday = 1 SetVar Monday = 2 SetVar Tuesday = 3 SetVar Wednesday = 4 SetVar Thursday = 5 SetVar Friday = 6 SetVar Saturday = 7 Here is a way to control when people can logon and play games (or what ever it is that you might need to control). This needs to be either included in a logon UDC, or in a command file executed from one. If HPDay = Sunday or HPDay = Saturday or & HPHour < 8 or HPHour > 17 or HPHour = 12 Then If HPUSERCOUNT < (HPUSERLIMIT / 2) Then Echo Echo Welcome to the Game Room. Else Echo Echo Sorry, the system is too busy at this time to allow Echo you to play games. Please try again later. Bye EndIf Else Echo Echo Sorry, the Game Room is closed. Echo Hours: Saturday and Sunday: all day Echo Monday-Friday: Before 8 a.m., After 5 p.m. Echo and Noon to 1 p.m. Bye EndIf If it is Saturday or Sunday, or before 8 a.m., after 5 p.m., or sometime during the noon hour, this will let the user stay logged on any other time the user will automatically be logged off. Note that if the user gets logged on during an "open" time, they can continue playing forever there is nothing to force them off when the game room closes. To accomplish this, a check could be added to each of the commands set up to run the individual games. The comparison of HPUSERCOUNT against HPUSERLIMIT simply keeps people out of the games logon if more than half of the available logons have been used. Again, there is nothing to force them off if that becomes true after they have logged on. The first IF command assumes the existence of the variables for the days of the week. If they are not available, the correct numbers will need to be substituted in the IF command. For more examples, take a look in the INTEREX CSL (primarily in the COMMAND group). There are a number of interesting command files there. I am sure there are some CSL programs that utilize the predefined variables, although I can not point you to any specific examples. Another good source of examples is virtually any job stream from Hewlett-Packard Company. They tend to make extensive use of variables to control the flow of the job stream logic, and many of them are the predefined variables. 2.4.2 Programmatic examples. The following is a COBOL II/XL program that illustrates how to use the HPCIPUTVAR intrinsic. As it is presented, it allows the user to provide a value for the CI prompt (instead of the colon, for example), and the CI time out variable. 001000$CONTROL BOUNDS 001100 IDENTIFICATION DIVISION. 001200 PROGRAM-ID. PUTVAR. 001300 AUTHOR. DAVID L LARGENT . 001400 DATE-WRITTEN. TUE, JUL 6, 1993, 5:53 AM. 001500 ENVIRONMENT DIVISION. 001600 CONFIGURATION SECTION. 001700 SOURCE-COMPUTER. HP3000. 001800 OBJECT-COMPUTER. HP3000. 001900 SPECIAL-NAMES. 002000 CONDITION-CODE IS CC. 002200 DATA DIVISION. 002400 WORKING-STORAGE SECTION. 002700****************************** 002800* Sets the HPPrompt and * 002900* HPTimeOut Variables * 003000****************************** 003200 01 ITEM-1 PIC S9(9) COMP 003300 VALUE 1. 003400 01 ITEM-2 PIC S9(9) COMP 003500 VALUE 2. 003600 01 ITEM-11 PIC S9(9) COMP 003700 VALUE 11. 003800 01 TIME-OUT PIC 9(3) . 003900 01 VAR-NAME PIC X(15) . 004000 01 VAR-STATUS PIC S9(9) COMP . 004100 01 VAR-VALUE-I PIC S9(9) COMP . 004200 01 VAR-VALUE-S PIC X(20) . 004300 01 VAR-VALUE-S-SIZE PIC S9(9) COMP 004400 VALUE 20. 004600 PROCEDURE DIVISION. 004800 MAIN-LINE-SECTION SECTION. 005000 MAIN-LINE. 005200 DISPLAY "What do you want the prompt set to?". 005300 ACCEPT VAR-VALUE-S. 005400 MOVE "HPPROMPT " TO VAR-NAME. 005500 MOVE ZERO TO VAR-STATUS. 005600 CALL INTRINSIC "HPCIPUTVAR" USING VAR-NAME VAR-STATUS ITEM-2 005700 VAR-VALUE-S ITEM-11 VAR-VALUE-S-SIZE. 005800 IF VAR-STATUS NOT = ZERO 005900 DISPLAY "Program PUTVAR: " VAR-NAME " not set." 006000 ELSE 006100 DISPLAY "Program PUTVAR: The prompt was set to " 006200 VAR-VALUE-S 006300 . 006400 DISPLAY "What do you want the time out length set" 006500 " to? (3 digits) ". 006600 ACCEPT TIME-OUT. 006700 MOVE TIME-OUT TO VAR-VALUE-I. 006800 MOVE "HPTIMEOUT " TO VAR-NAME. 006900 MOVE ZEROS TO VAR-STATUS. 007000 CALL INTRINSIC "HPCIPUTVAR" USING VAR-NAME VAR-STATUS ITEM-1 007100 VAR-VALUE-I. 007200 IF VAR-STATUS NOT = ZERO 007300 DISPLAY "Program PUTVAR: " VAR-NAME " not set." 007600 ELSE 007700 MOVE VAR-VALUE-I TO TIME-OUT 007800 DISPLAY "Program PUTVAR: The time out length was set to " 007900 TIME-OUT 008000 . 008100 STOP RUN. I'll have to admit this is not a very useful program. It does however, show the basics of what needs to be done to create and/or set a particular variable to a given value. If your variable name is longer than fourteen characters, make sure you increase the length of field VAR-NAME. Also, make sure you have at least one blank or other non- alphanumeric character following your variable name. Here is another example COBOL II/XL program with the HPCIGETVAR intrinsic, which shows the basics of what needs to be done to retrieve the value of an existing variable. 001000$CONTROL BOUNDS 001100 IDENTIFICATION DIVISION. 001200 PROGRAM-ID. DISPLAYVAR. 001300 AUTHOR. DAVID L LARGENT . 001400 DATE-WRITTEN. TUE, JUL 6, 1993, 4:27 AM. 001500 ENVIRONMENT DIVISION. 001600 CONFIGURATION SECTION. 001700 SOURCE-COMPUTER. HP3000. 001800 OBJECT-COMPUTER. HP3000. 001900 SPECIAL-NAMES. 002000 CONDITION-CODE IS CC. 002200 DATA DIVISION. 002400 WORKING-STORAGE SECTION. 002700************************************************ 002800* Finds and Displays the Job's Information * 003000************************************************ 003200 01 ITEM-1 PIC S9(9) COMP 003300 VALUE 1. 003400 01 ITEM-2 PIC S9(9) COMP 003500 VALUE 2. 003600 01 ITEM-10 PIC S9(9) COMP 003700 VALUE 10. 003800 01 JOB-NUMBER PIC 9(6) . 003900 01 JOB-TYPE PIC X . 004000 01 VAR-NAME PIC X(15) . 004100 01 VAR-STATUS PIC S9(9) COMP . 004200 01 VAR-VALUE-I PIC S9(9) COMP . 004300 01 VAR-VALUE-S PIC X(8) . 004400 01 VAR-VALUE-S-SIZE PIC S9(9) COMP 004500 VALUE 8. 004700 PROCEDURE DIVISION. 004900 MAIN-LINE-SECTION SECTION. 005100 MAIN-LINE. 005300 MOVE "HPJOBNAME " TO VAR-NAME. 005400 MOVE ZERO TO VAR-STATUS. 005500 MOVE SPACES TO VAR-VALUE-S. 005600 CALL INTRINSIC "HPCIGETVAR" USING VAR-NAME VAR-STATUS ITEM-2 005700 VAR-VALUE-S ITEM-10 VAR-VALUE-S-SIZE. 005800 IF VAR-STATUS NOT = ZERO 005900 DISPLAY "Program DISPLAYVAR: " VAR-NAME " not found." 006000 ELSE 006100 DISPLAY "Program DISPLAYVAR: The job/session's name is " 006200 VAR-VALUE-S 006300 . 006400 MOVE "HPUSER " TO VAR-NAME. 006500 MOVE ZERO TO VAR-STATUS. 006600 MOVE SPACES TO VAR-VALUE-S. 006700 CALL INTRINSIC "HPCIGETVAR" USING VAR-NAME VAR-STATUS ITEM-2 006800 VAR-VALUE-S ITEM-10 VAR-VALUE-S-SIZE. .....(continued)..... .....(continued)..... 006900 IF VAR-STATUS NOT = ZERO 007000 DISPLAY "Program DISPLAYVAR: " VAR-NAME " not found." 007100 ELSE 007200 DISPLAY "Program DISPLAYVAR: The user's name is " 007300 VAR-VALUE-S 007400 . 007500 MOVE "HPJOBTYPE " TO VAR-NAME. 007600 MOVE ZERO TO VAR-STATUS. 007700 MOVE SPACES TO VAR-VALUE-S. 007800 CALL INTRINSIC "HPCIGETVAR" USING VAR-NAME VAR-STATUS ITEM-2 007900 VAR-VALUE-S ITEM-10 VAR-VALUE-S-SIZE. 008000 IF VAR-STATUS NOT = ZERO 008100 DISPLAY "Program DISPLAYVAR: " VAR-NAME " not found." 008200 MOVE SPACES TO JOB-TYPE 008300 ELSE 008400 MOVE VAR-VALUE-S TO JOB-TYPE 008500 . 008600 MOVE "HPJOBNUM " TO VAR-NAME. 008700 MOVE ZEROS TO VAR-STATUS 008800 VAR-VALUE-I. 008900 CALL INTRINSIC "HPCIGETVAR" USING VAR-NAME VAR-STATUS ITEM-1 009000 VAR-VALUE-I. 009100 IF VAR-STATUS NOT = ZERO 009200 DISPLAY "Program DISPLAYVAR: " VAR-NAME " not found." 009300 MOVE ZERO TO JOB-NUMBER 009400 ELSE 009500 MOVE VAR-VALUE-I TO JOB-NUMBER 009600 . 009700 DISPLAY "Program DISPLAYVAR: The job/session # is " JOB-TYPE 009800 JOB-NUMBER. 009900 STOP RUN. Same comments as last time; make sure you set up VAR-NAME large enough to hold your variable name and make sure you end it with at least one blank or other nonalphanumeric character. 3 Closing thoughts "For a good time... check out HPSusan!" We have looked (stared?!) at HPSUSAN and her harem, the MPE/iX predefined variables. Numerous examples have been explored to see how they work and how they can be used. Even so, there are still a few predefined variables that have not been mentioned. We have found that they will tell us virtually anything we might want to know except how old they are. They are a very powerful feature of the HP 3000 and MPE/iX. So, is it worth the effort of learning something new? My answer is a resounding YES! Use of the predefined variables must be carefully planned and monitored to reap the greatest benefit, but, oh, what a benefit it is: Increased operator, programmer, and user productivity and a computer system that is easier to use overall. HP is a trademark of Hewlett-Packard Company. Acknowledgments A special thanks go to the following people who assisted in creating this paper in some way all of their efforts (and tolerance!) are greatly appreciated: Dan Hinds Jonathan Largent Julia Largent Lois Largent Jamie Lunsford Bibliography Cressler, Scott; Vance, Jeff; and Elmer, Steve "Advanced CI Programming: The 2.1 Story", Interact, February, 1991, page 83ff. Dunlop, John "CI Programming in MPE XL/iX or What the Manuals Don't Say", Interact, November, 1992, page 78ff. Hewlett-Packard Company "Command I/O Redirection", Communicator 3000/XL, Volume 6, Issue 1, May, 1991, page 9-10ff. Hewlett-Packard Company Command Interpreter Access and Variables Programmer's Guide, Second Edition, 1990, All Chapters. Hewlett-Packard Company Command Interpreter Programming Quick Reference Card, December, 1990. Hewlett-Packard Company Getting System Information Programmer's Guide, First Edition, Update 1, 1988, Chapter 3. Hewlett-Packard Company MPE V to MPE XL: Getting Started, Third Edition, 1989, Chapter 5 & 7. Hewlett-Packard Company MPE XL Intrinsics Reference Manual, Third Edition, 1990, Chapters 2 & 4. Hewlett-Packard Company MPE/iX Commands Reference Manual Volume I, Fifth Edition, 1992, Chapter 2. Hewlett-Packard Company MPE/iX Commands Reference Manual Volume II, First Edition, 1992, Chapter 2 and Appendix A. Hewlett-Packard Company Mountain View Response Center Calls to the Mountain View HP Response Center during June, 1993. Hewlett-Packard Company North American Response Centers HP3000 Application Note #21: COBOLII and MPE Intrinsics, January 15, 1987. Hewlett-Packard Company North American Response Centers HP3000 Application Note #94: RPG/XL Intrinsic Interface, January 15, 1992. INTEREX INTEREX Contributed Software Libraries (1990-1992). Largent, David L. "Function Key Labeling", Interact, February, 1988, page 15. Largent, David L. "JCWs: An Introduction", Interact, April, 1991, page 36ff. Manise, Walter "Questions & Answers", Interact, March, 1992, page 12ff. Parker, Michael J. and Wilson, Lynn "Labeling F-keys", Interact, November, 1987, page 22ff. Pratt, Bruce "UDCs vs. Command Files", Interact, September, 1992, page 10ff. Index Account. . . . . . . . . . . . . . . . . . . 13-14, 16, 20-21 CI . . . . . . . . . . . . . . . .6, 8, 13, 14, 19, 21-22, 31 CIERROR. . . . . . . . . . . . . . . . . . . . . . . . . 6, 7 COBOL. . . . . . . . . . . . . . . . . . . . . .8, 10, 26, 28 Command File . . . . . . . . . . . . .5, 6, 13-15, 18, 21, 25 Command Files. . . . . . . . . . . . . . . . . .1, 14, 21, 26 Command Interpreter. . . . . . . . . . . . . . . . .6, 19, 23 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . .7, 26 Delete . . . . . . . . . . . . . . . . . . . . . . . . .5, 20 DELETEVAR. . . . . . . . . . . . . . . . . . . . . .5, 22, 23 ECHO . . . . . . . . . . . . . . . . 13, 15, 18-19, 22, 25-26 ELSE . . . . . . . . . . . . . . 7, 9, 11, 14, 17, 21, 26, 29 ELSEIF . . . . . . . . . . . . . . . . . . . 7, 16, 19, 22-23 ENDIF. . . . . . . . . . . . . . . . 7, 14, 17, 19, 22, 25-26 ENDWHILE . . . . . . . . . . . . . . . . . . . . . .7, 18, 19 ERRCLEAR . . . . . . . . . . . . . . . . . . . . . . . .3, 22 Errors . . . . . . . . . . . . . . . . . . . . . . . . .3, 20 EXIT . . . . . . . . . . . . . . . . . . . . . . . . 7, 21-22 FINFO. . . . . . . . . . . . . . . . . . . . . . . . . 16, 20 Function Keys. . . . . . . . . . . . . . . . . . . . . . . 20 HPACCOUNT. . . . . . . . . . . . . . . . . . . 13, 14, 18, 20 HPACCTCAPF . . . . . . . . . . . . . . . . . . . . . . . . 14 HPAUTOCONT . . . . . . . . . . . . . . . . . . . . . . 18, 20 HPCIDELETEVAR. . . . . . . . . . . . . . . . . . . . . . . .5 HPCIDEPTH. . . . . . . . . . . . . . . . . . . . . 13, 14, 22 HPCIERR. . . . . . . . . . . . . . . . . . . . .7, 18, 20, 22 HPCIERRCOL . . . . . . . . . . . . . . . . . . . . . . . . .7 HPCIGETVAR . . . . . . . . . . . . . . . . . . . . . 8, 28-29 HPCIPUTVAR . . . . . . . . . . . . . . . . . . . 8, 10, 26-27 HPCMDNUM . . . . . . . . . . . . . . . . . . . . . . . 13, 14 HPCONNMINS . . . . . . . . . . . . . . . . . . . . . . 13, 14 HPCONNSECS . . . . . . . . . . . . . . . . . . . . . . 23, 24 HPCONSOLE. . . . . . . . . . . . . . . . . . . . . . . 22, 24 HPCPUNAME. . . . . . . . . . . . . . . . . . . . . . . . . 15 HPCPUSECS. . . . . . . . . . . . . . . . . . . . . . . 13, 14 HPDATE . . . . . . . . . . . . . . . . . . . . . . . . 18, 20 HPDATEF. . . . . . . . . . . . . . . . . . . . . . 13, 14, 17 HPDAY. . . . . . . . . . . . . . . . . . . . . . . . . .5, 25 HPDTCPORTID. . . . . . . . . . . . . . . . . . . . . . 13, 14 HPEXECJOBS . . . . . . . . . . . . . . . . . . . . . . . . 15 HPFSERR. . . . . . . . . . . . . . . . . . . . . . . . . . .7 HPGROUP. . . . . . . . . . . . . . . . . . . . . . . . 13, 14 HPGROUPCAPF. . . . . . . . . . . . . . . . . . . . . . . . 14 HPHGROUP . . . . . . . . . . . . . . . . . . . .13, 14, 20-21 HPHOUR . . . . . . . . . . . . . . . . . . . . . . 18, 20, 25 HPINBREAK. . . . . . . . . . . . . . . . . . . . . . . . . 14 HPINTERACTIVE. . . . . . . . . . . . . . . . . . . . . . . 22 HPINTRODATE. . . . . . . . . . . . . . . . . . . . . . 13, 14 HPINTROTIME. . . . . . . . . . . . . . . . . . . . . . 13, 14 HPJOBCOUNT . . . . . . . . . . . . . . . . . . . . . . . . 15 HPJOBFENCE . . . . . . . . . . . . . . . . . . . . . . . . 15 HPJOBLIMIT . . . . . . . . . . . . . . . . . . . . . . . . 15 HPJOBNAME. . . . . . . . . . . . . . . . . .4, 14, 24, 25, 28 HPJOBNUM . . . . . . . . . . . . . . . . . . . . . 13, 14, 29 HPJOBTYPE. . . . . . . . . . . . . . . . . . . . . 13, 14, 29 HPLDEVIN . . . . . . . . . . . . . . . . . 13, 14, 22, 24, 25 HPLDEVLIST . . . . . . . . . . . . . . . . . . . . . . 13, 14 HPMINUTE . . . . . . . . . . . . . . . . . . . . . . . 18, 20 HPMONTH. . . . . . . . . . . . . . . . . . . . . . . . 18, 20 HPMSGFENCE . . . . . . . . . . . . . . . . . . . . . . 13, 20 HPOUTFENCE . . . . . . . . . . . . . . . . . . . . . . . . 15 HPPATH . . . . . . . . . . . . . . . . . . . . . . . . 13, 14 HPPROMPT . . . . . . . . . . . . . . . . . . . . . . . .19-20 HPQUIET. . . . . . . . . . . . . . . . . . . . . . . . 13, 14 HPREDOSIZE . . . . . . . . . . . . . . . . . . . .5-6, 13, 14 HPSCHEDJOBS. . . . . . . . . . . . . . . . . . . . . . . . 15 HPSESCOUNT . . . . . . . . . . . . . . . . . . . . . . . . 15 HPSESLIMIT . . . . . . . . . . . . . . . . . . . . . . . . 15 HPSUSAN. . . . . . . . . . . . . . . . . . . . . . 1-2, 15-16 HPSUSPJOBS . . . . . . . . . . . . . . . . . . . . . . . . 15 HPSYSNAME. . . . . . . . . . . . . . . . . . . . . . . 15, 21 HPTIMEF. . . . . . . . . . . . . . . . . . . . . . 13, 14, 23 HPTIMEOUT. . . . . . . . . . . . . . . . . . . .6, 13, 14, 20 HPTYPEAHEAD. . . . . . . . . . . . . . . . . . . . . . 13, 14 HPUSER . . . . . . . . . . . . . . . . . . 13, 14, 18, 24, 28 HPUSERCAPF . . . . . . . . . . . . . . . . . . . . . . . . 14 HPUSERCMDEPTH. . . . . . . . . . . . . . . . . . . . . 13, 14 HPUSERCOUNT. . . . . . . . . . . . . . . . . . . . 15, 25, 26 HPUSERLIMIT. . . . . . . . . . . . . . . . . . . . 15, 25, 26 HPVERSION. . . . . . . . . . . . . . . . . . . . . . . . . 15 HPWAITJOBS . . . . . . . . . . . . . . . . . . . . . . . . 15 HPYEAR . . . . . . . . . . . . . . . . . . . . . . . . 18, 20 IF . . . . . . . . . . . . . .1, 4, 8, 12, 14, 17, 19, 25, 29 INPUT. . . . . . . . . . . . . . . . . . 3, 5-6, 13-14, 18-20 INTR . . . . . . . . . . . . . . . . . . . . . . . . . 10, 12 JCW. . . . . . . . . . . . . . . . . . . . . . 2, 7-8, 10, 11 Logon. . . . . . . . . . . . . . . . . . . .13-14, 22, 25, 26 Menu . . . . . . . . . . . . . . . . . . . . . . . . 1, 19-20 Mnemonic . . . . . . . . . . . . . . . . . . . . . . 7, 8, 19 NoBreak. . . . . . . . . . . . . . . . . . . . . . 18, 20, 21 Parameter. . . . . . . . . . . . . . . . . . 5, 10-12, 23, 25 Parm . . . . . . . . . . . . . . . . . . . . . . . . . 18, 22 PUTJCW . . . . . . . . . . . . . . . . . . . . . . . . . . .8 RPG. . . . . . . . . . . . . . . . . . . . . . . . . . 10, 32 SETJCW . . . . . . . . . . . . . . . . . . . . . . . . . . .3 SETVAR . . . . . . . . . . . . . . . . . 3, 8, 10, 17, 21, 25 SHOWJCW. . . . . . . . . . . . . . . . . . . . . . . . . . .3 Status . . . . . . . . . . . . . . . . . . .8, 11, 18, 27, 29 STR. . . . . . . . . . . . . . . . . . . . . . . . . . 16, 18 UDC. . . . . . . . . . . . . . . . . . . . . . . 5, 6, 20, 22 Underscore . . . . . . . . . . . . . . . . . . . . . . . . .8 Variable . . . . . . . .2, 4, 8, 10-11, 14, 15, 18, 24-26, 29 Warning. . . . . . . . . . . . . . . . . . . 6, 9, 11, 20, 23 Warnings . . . . . . . . . . . . . . . . . . . . . . . .9, 20 WHILE. . . . . . . . . . . . . . . . . . . . . .7, 14, 20, 21