HP 3000 Manuals HP 3000 Manuals
Common RPM Parameters The following discussion of the flags and result parameters may help to clarify the more condensed information given under each intrinsic. Flags Parameter The flags parameter is a bit representation, 32 bits long, of various options. Normally an option is invoked if the appropriate bit is on (that is, set equal to 1). Borrowing Pascal-type syntax, we shall use flags [0] to refer to the high order bit in the two-word parameter, flags [31] to refer to the low order bit, and a similar designation to refer to each of the bits in between. Bits that are not defined for a given intrinsic must be off (zero). Result Parameter If an RPM intrinsic call is successful, the result parameter will return a zero. Otherwise, the value returned represents an RPM error code. RPM error messages are listed in the NS3000/XL Error Messages Reference Manual. You can also obtain the appropriate error message by calling IPCERRMSG.
NOTE When nowait I/O is used, the result parameter is not updated upon completion of an intrinsic. Therefore, the value of result will indicate only whether the call was successfully initiated. To determine whether the call completed successfully, you can use the IPCCHECK intrinsic immediately afterward.
In addition, when called on an HP 3000, these intrinsics cause MPE condition codes to be set. Usually CCE indicates successful completion, CCL indicates failure, and CCG is either not used or represents a warning. RPMCONTROL Controls the execution of an existing process that was created by an RPMCREATE. Syntax _____________________________________________________________________________ | | | RPMCONTROL (pd [,location][,loclen],reqcode [,wrtdata][,wrtlen]| | [,readdata][,readlen][,flags][,result]) | _____________________________________________________________________________ Parameters pd (input) 16-byte array, by value. Eight word program descriptor identifying the remote process to access. location (input) Character array, by reference. Character string identifying the node on which the remote process resides. loclen (input) 32-bit integer, by value. Length in bytes of the location parameter. reqcode (input) 32-bit integer, by value. The number signifying the request for the RPMCONTROL call. Currently defined options for RPMCONTROL are: * 20001 - Suspend execution of the remote process. No data is required, and none is returned. * 20002 - Resume execution of the remote process at the point it was suspended. No data is required, and none is returned. wrtdata (input) Byte array, by reference. Any data to be sent to the remote side for the request. wrtlen (input) 32-bit integer, by value. Length, in bytes of wrtdata. readdata (output) Byte array, by reference. Data to be returned to the caller. readlen (input/output) 32-bit integer, by reference. On input, it is the maximum number of bytes expected in the readdata parameter. On output, it is the actual number of bytes received in the readdata parameter. flags (input) 32 bits, by reference. A bit representation of various options. No flags are currently defined. result (output) 32-bit integer, by reference. The result of the RPMCONTROL request; zero if no error. Description This intrinsic is used to control a remote process that was created with an RPMCREATE request. The only RPM control requests defined are suspend and resume. Its calling sequence is similar to that of IPCCONTROL. The pd and reqcode parameters are the only required parameters. To control a remote process from a process which is not its creator, the location and loclen must be specified. RPMCONTROL uses these parameters to establish a new connection to the remote machine to perform the request. The wrtdata and wrtlen parameters must be specified if the reqcode specified requires data to be transferred to the remote node. Similarly, readdata and readlen should be included if the reqcode specified returns data to the caller upon completion of the request. Presently, there are no request codes that require these parameters. The ability to specify the suspend and resume request codes (20001, 20002) in an RPMCONTROL request is limited to programs that have Privileged Mode (PM) capability. Great care should be taken when using these request codes. If a locally created process is suspended, (that is, a process that was created with a location and logon matching that of the caller, or the location and logon were omitted or blank), and the creator terminates without issuing either an RPMKILL or an RPMCONTROL with the resume request code, the creator process may hang. Therefore, these functions should not be used to manipulate locally created processes unless absolutely necessary. If the process to be suspended is on a remote node, there is no danger of hanging the process. However, a process that has been suspended in this manner cannot be killed or resumed except by explicitly calling either RPMKILL orRPMCONTROL with the resume request code. If a process is in a state where the node cannot suspend it, RPMCONTROL will return an error code in the result parameter indicating this. A process may not be suspendable because: the process is suspended by a system process, the process is waiting for critical resources, or the process is dying. RPMCREATE Creates and activates a process and, if necessary, creates a remote session for that process to run in. Process Handling (PH) capability is required. Syntax _____________________________________________________________________________________ | | | RPMCREATE (progname,namelen [,location][,loclen][,login][,loginlen]| | [,password][,passwdlen][,flags][,opt][,pd][,result]) | _____________________________________________________________________________________ Parameters progname (input) Character array, by reference. The name of the program for which a process is to be created. namelen (input) 32-bit integer, by value. The length in bytes of the program name. location (input) Character array, by reference. The node name or environment ID indicating where the process should be created. loclen (input) 32-bit integer, by value. The length in bytes of the location name. login (input) Character array, by reference. A logon sequence for the local or remote node on which the process is to be created, in the form [ session ,] user.acct [, group ]. loginlen (input) 32-bit integer, by value. The length in bytes of the logon sequence. password (input) Character array, by reference. Password(s) to be used with the logon sequence, in the form [ userpass ][,acctpass ][,grouppass]. passwdlen (input) 32-bit integer, by value. The length in bytes of the password parameter. flags (input) 32 bits, by reference. A bit representation of various options. The following flags are defined: * flags [0] (input). Indicates that all environment information given in a prior DSLINE command (for the remote environment in question) should be ignored when the new process is created. For example, if this flag is on, a logon sequence provided in the LOGON option of a DSLINE command will not override the logon given in this RPMCREATE call. * flags [1](input). Causes the calling process to wait in this intrinsic call until the new process terminates. (The RPMCREATE call will complete only after the new process finishes executing.) * flags [2] (input). Causes RPM to create a process using RPM protocols from HP's software release UB Delta 1 or earlier. In software release UB Delta 1 or earlier, RPM flags 3 and 30 are not supported. * flags [3](input). Causes RPMCREATEto fail if the remote node has a version of RPM installed that is from HP's software release UB Delta 1 or earlier. By default, if the remote node does not have the newer RPM installed, RPMCREATEwill act as if flags [2] is set and conform to the older format * flags [30](input). Causes the remote node to create the process into a session that may accommodate multiple RPM created processes. By defaultRPMCREATE will only create one remote process per remote session. * flags [31](input). Makes the created process dependent on the creator. When the creator process dies, the created process will be killed. (If this bit is off, the created process will continue executing on its own.) Default: off; created process is independent of its creator. opt Record or byte array, by reference. A list of options, with associated information. The following options are defined: * RPM string (option code 20000, n-byte array). Permits information to be sent to the created process in the data portion of the opt parameter, such as a socket name. More than one RPM string can be included. The strings may be retrieved by the new process (using RPMGETSTRING) in the same order that they occur in the opt parameter. * Entry point (code 22001,n-byte array). The data portion of this parameter contains a string, terminated by a blank, specifying the entry point (label) in the program where execution is to begin when the process is activated. A blank by itself indicates the primary entry point. This parameter corresponds to item number 1 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. Default: primary entry point. * Program parameter (code 22002, 2-byte integer). The data portion of this parameter contains an integer value used to transfer control information to the new process. The word will be accessible on the stack of the new process at location Q-4. This parameter corresponds to item number 2 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in theCREATEPROCESS intrinsic. * Create flags (code 22003, 2-byte bit map). The data portion of this parameter contains a word whose bits specify loading options, as follows. (Bit 15 is the least significant bit, bit 0 the most significant bit.) This parameter corresponds to item number 3 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. * bit 15--Ignored; should be off. * bit 14-- LOADMAP bit. If on, a listing of the newly allocated program is produced on the job/session listing device. This map shows the Code Segment Table (CST) entries used by the new process. Default: off. * bit 13-- DEBUG bit. If on, DEBUG is called at the first executable instruction of the new program. You must have read/write access to the program file of the new process. If the new process requires privileged mode, you must be a privileged user. Default: off. * bit 12-- NOPRIV bit. If on, the slave program is loaded in non-privileged mode. If this bit is off, the program is loaded in the mode specified when the program file was prepared. Default: off. * bits 10 and 11-- LIBSEARCH bits. A coded bit pattern that denotes the order in which libraries are to be searched for the program. The default is 00: 00 = System Library only. 01 = Account Public Library, then System Library. 10 = Group Library, then Account Public Library, then System Library. * bit 9-- NOCB bit. If on, file system control blocks are established in an extra segment. If off, control blocks may be established in the Process Control Block Extension (PCBX) area. Default: off. This bit should be set on if the new process uses a large stack. * bits 7 and 8--reserved for MPE; should be off (00). * bits 5 and 6-- STACKDUMP bits. A coded bit pattern that controls the enabling/disabling of stack dumping in the event of a program abort. The default is 00: 00 = enable stack dumping for new process only if enabled at master level; 01 = enable stack dump unconditionally; 10 = same as 00; 11 = disable stack dump unconditionally. * bit 4--reserved for MPE; should be off. * bits 0 to 3--These four bits are used only if the STACKDUMP bits are 01; otherwise they are ignored. Bits 1-3 represent portions of the slave program's stack. If bit 3 is on, the portion of the stack from DL to QI (Q-initial) is dumped; if off, this portion is not dumped. If bit 2 is on, the portion of the stack from QI to S is dumped. If bit 1 is on, the portion of the stack from Q-63 to S is dumped. If bit 0 is on, the stack dump is interpreted in ASCII characters in addition to octal values; if off, no ASCII interpretation is performed. The default for each of these bits is off. The default conditions noted above take effect if the Create flags option (flags) or the entire opt parameter is omitted . * Initial stack size (code 22004, 2-byte integer). The data portion of this parameter contains an integer (Z - Q) denoting the size, in words, of the local stack area bounded by the initial Q and Z values. This parameter corresponds to item number 4 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESSintrinsic. Default: The value specified in the program file. * Initial dlsize (code 22005, 2-byte integer). The data portion of this parameter contains an integer (DB - DL) denoting the size, in words, of the user-managed stack area bounded by the DL and DB values. This parameter corresponds to item number 5 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. Default: The value specified in the program file. * Max stack size (code 22006, 2-byte integer). The data portion of this parameter contains an integer (Z - DL) denoting the maximum word size allowed for the process's stack area (bounded by the DL and Z values). This parameter corresponds to item number 6 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. Default: The value specified in the program file or (if none is specified there) the current stack size. * Priority (code 22007, 2-byte array). The data portion of this parameter contains a string of two ASCII characters (AS, BS, CS, DS, or ES) indicating the priority class in which the new process is scheduled. Default: The same priority as the calling process. This parameter corresponds to item number 7 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. * $STDIN file name (code 22008, n-byte array). The data portion of this parameter contains the name of a file to which all input requests to $STDIN will be directed. This parameter corresponds to item number 8 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. Default: With an interactive logon ( HELLO, REMOTE HELLO), input requests will be directed to $STDIN. With the logon option(either the LOGON=parameter in aDSLINE command or the login parameter of RPMCREATE ), input requests will be directed to the empty file $NULL. * $STDLIST file name (code 22009, n-byte array). The data portion of this parameter contains the name of a file to which all output requests to $STDLISTwill be directed. This parameter corresponds to item number 9 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in theCREATEPROCESS intrinsic. Default: With an interactive logon ( HELLO, REMOTE HELLO), output requests will be directed to $STDLIST. With the logon option (either the LOGON= parameter in a DSLINE command or the login parameter of RPMCREATE), output requests will be directed to the empty file $NULL. * Info string (code 22011, n-byte array). The data portion of this parameter contains an information string that is passed to the new process. This string will be accessible on the new process's stack at a byte address that is stored at location Q-5. If this option is included, you must also include the Info string length option (22012). This parameter corresponds to item number 11 of the MPE XL CREATEPROCESS intrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. * Info string length (code 22012, 2-byte integer). The data portion of this parameter contains an integer specifying the byte length of the info string given by the previous option. The Info string length option must be included if the Info string option is included. This parameter corresponds to item number 12 of the MPE XL CREATEPROCESSintrinsic. The contents of this option parameter should conform to the value of the item parameter in the CREATEPROCESS intrinsic. * Logon timeout; real (code 22100, 4-byte real value). The data portion of this parameter contains a real value representing the number of seconds you are willing to wait for a remote logon, performed by RPMCREATE, to complete. If the remote session is not established during this time, you will receive an error. Default: 120.0 seconds. * Logon timeout; integer (code 22102, 4-byte integer). This is the same as option 22100 except that the data portion of this parameter contains an integer representing the number of milliseconds that you are willing to wait for the remote logon, performed by RPMCREATE to complete. If both options are present in the opt array, then the entry with the lowest array index will be the one selected. pd (output) 16-byte array, by reference. A program descriptor used to identify the created process. This value, randomly generated, is presumed to be unique across all nodes. A valid program descriptor is always a non-zero value. result (output) 32-bit integer, by reference. The error code returned; zero if no error. Description The RPMCREATE intrinsic enables the calling process to create and activate another process--that is, to initiate execution of another program. The new process may be on a remote system. (RPM does not extend the process management capabilities of a particular operating system, such as MPE, across a network.) Normally, RPMCREATE allows only one remote process per remote session. Bit 30 of the RPM flags parameter allows multiple RPM remote processes in a remote session. This session-sharing option of RPM is only available in HP's software release UB delta 2 or later. The only required parameters are progname, namelen, location, and loclen. (The intrinsic is option variable.) In order for multiple processes to reside in a common remote session, three criteria must be satisfied: * All the processes must have been created with bit 30 of the flags parameter set. Remote processes created without this bit set will not share sessions with processes that do have it set. * All the processes must have been created from processes residing within the same session on the local node. Processes that are running in different local sessions will RPMCREATE remote processes into different remote sessions. * All the processes must have the same logon string including session name, if any. All the necessary passwords must match. The remote session may be any session that RPMCREATE would normally use, including VT-created sessions, that is, sessions created using the REMOTE HELLO command. The new process will run in an existing remote session (created by REMOTE HELLO) if you specify the appropriate environment ID in the location parameter. A new session will be created on the remote node if one does not already exist. RPM uses the logon sequence specified in thelogin parameter (and the password in password) unless (1) a logon is specified in a prior DSLINEcommand for the remote environment (in the LOGON option), and (2) bit 0 of the flags parameter (the high-order bit, which causes the DSLINE information to be ignored) is off. In other words, the order of priority (from high to low) is: existing session; DSLINE logon; RPMCREATE logon. But the "ignore DSLINE information" flag forces the use of the RPMCREATE logon instead of a DSLINE logon. If the new process is to be created on a remote node and the login parameter is omitted, then a remote session must already exist or logon information must be given in a prior DSLINE command. For example, let's say that a previous DSLINE command has defined 'S' as an environment ID for node FINANCE, with logon USER.ACCT. Then an RPMCREATE call giving 'S' as the location and omitting the login parameter will create a session on FINANCE for USER.ACCT. Once an RPMCREATE call has been made for a remote environment, you cannot issue remote commands for that environment until the remote process has terminated (for example, has been killed via RPMKILL). If an independent RPM process has been left in the remote environment after the process that created it has terminated, and you issue a DSLINE ;CLOSEcommand for the remote environment, you will first be asked whether you want to kill the remote RPM process. If you kill the remote process and then do not abort the remote session, you can subsequently issue commands in the remote session. See "Releasing a Remote Environment" in the "Virtual Terminal" chapter of this manual. RPMCREATE can also create a new process on the local node. The new process will be created in your local session if (1) the location andlogin parameters are omitted or blank or (2)location is the local node name and login is the logon for your local session (including session name, if any). A new process will also be created on your local node, but in a different session, if (1) you specify your local node name, and a logon different from your own and (2) software loopback has been configured and activated for your local node. Bit 31 (the low-order bit) of the flags parameter determines whether the newly created process will be dependent on its creator or independent (the default). A local dependent process that was created under the same logon as its creator will terminate automatically when the creator terminates. (In order to conserve system resources, you should make local processes independent; that is, set the bit off.) A remote dependent process will terminate if: * RPMKILL has been called for the dependent process. * The creator process terminates before calling RPMKILL. * The transport fails. * The system on which the creator is running fails. If the remote process is independent, it will continue to execute unless explicitly terminated by RPMKILL. Dependent mode ensures that the new process will not become an "orphan" in the event of a program, system, or network link failure. However, independent mode is less costly in terms of resources: the connection set up for the RPMCREATE is not maintained after the remote process is created. You should normally use independent mode for processes that are expected to terminate themselves. Preferred Method of Creating Interactive Programs RPM works best to create non-interactive server programs on a remote system. If you use RPM to create interactive programs, some restrictions exist (described in a following section). Therefore, as an alternative to using the RPMCREATE intrinsic to create interactive programs, HP recommends that you call the REMOTE RUN command from the COMMAND intrinsic. Using this method will suspend the master process in the COMMAND intrinsic while the slave program runs. Only use RPMCREATE if you require parallel execution of a master and slave process. Using $STDIN and $STDLIST in a Precreated VT Session Beginning with MPE XL release 2.2, remote RPM slave processes can post interactive I/O to $STDIN and $STDLIST through a precreated VT session. This allows interactive I/O from remote programs to appear on a local terminal. Before creating an RPM slave, use the REMOTE HELLO command to create a remote session. After the session is established, you can use the RPMCREATE command to create an RPM son in the remote session. The location parameter should contain the same environment name that was specified in the REMOTE HELLO command. Do not specify the login or loginlen parameters, nor are the $STDIN/$STDLIST options 22008/22009 required. Restrictions when Using RPMCREATE to Create Interactive Programs Because RPM was not designed to create interactive programs, there are caveats you should be aware of before using RPM for your application. Do not press the system BREAK or the subsystem break CTRL-y while a remote application is running. Do not create an RPM slave in a VT session that is in break. This will cause both the local and remote application to hang. Neither the local or remote session can log off. Opt Parameter Format The opt parameter, which denotes various options, contains an integer code for each option along with associated information. It is not necessary to know the internal structure of this parameter to use it. The "opt parameter manipulation intrinsics,"INITOPT, ADDOPT, and OPTOVERHEAD, enable you to add option information without concerning yourself with the parameter's structure. However, a knowledge of the opt parameter's structure can help you determine an appropriate size for the array. (The parameter must be defined as a byte array or as a record structured in the manner described below. If your program is written in a language that supports dynamically allowed arrays, the OPTOVERHEAD intrinsic may be used to determine the size of the array.) The opt parameter consists of these fields: * length, in bytes, of option entries and data (2-byte integer); * number of entries (2-byte integer); * option entries (8 bytes per entry); * data associated with the option entries (variable length). Each 8-byte option entry, in turn, consists of the following fields: * option code (2-byte integer); * offset (relative to the base address of the opt parameter) indicating the location of the data for this option entry (2-byte integer); * length, in bytes, of the data (2-byte integer); * unused (2 bytes). If the parameter is declared as a simple byte array, it must be large enough to contain 4 bytes for the first two fixed-length fields, 8 bytes for each option entry, plus the actual data. That is: 4 + 8 * numentries + datalength RPMGETSTRING Allows a created process to retrieve information strings passed to it by its creator in the RPMCREATE call. Syntax _________________________________________________________ | | | RPMGETSTRING (rpmstring,rpmstringlen,result)| _________________________________________________________ Parameters rpmstring (output) Character array, by reference. The string passed in the opt parameter of the RPMCREATE call that created this process. rpmstringlen (input/output) 32-bit integer, by reference. The maximum byte length allowed for the rpmstring. The returned value indicates the actual length of the returned rpmstring, zero if no string was passed by the creator process. result (output) 32-bit integer, by reference. The error code returned; zero if no error. Description The RPMGETSTRING intrinsic allows a process created by an RPMCREATE to obtain the information string passed to it by the creator process in the RPMCREATE call. All the parameters are required. The string obtained in this manner may contain any useful information. For example, it could contain the name of a (call) socket belonging to the creator along with the name of the node on which the creator is executing. The created process can look up this socket name in order to acquire a destination descriptor for it. After creating a socket of its own, it can establish a connection to the creator process. If the opt parameter of RPMCREATE contained more than one RPM string, you can issue several RPMGETSTRING calls to retrieve the strings. For example: Creator process: ADDOPT (Opt, 0, 20000, Length1, RpmString1); ADDOPT (Opt, 1, 20000, Length2, RpmString2); ADDOPT (Opt, 2, 20000, Length3, RpmString3); RPMCREATE (...Opt...); Created process: RPMGETSTRING (RpmString1, Length1, Result); RPMGETSTRING (RpmString2, Length2, Result); RPMGETSTRING (RpmString3, Length3, Result); For another illustration of the use of this intrinsic, see the program examples at the end of this chapter. RPMKILL Terminates a process created by the RPMCREATE intrinsic. Process Handling (PH) capability is required. Syntax _______________________________________________________ | | | RPMKILL ( pd[,location][,loclen][,result])| _______________________________________________________ Parameters pd (input) 16-byte array, by value. The program descriptor returned by the RPMCREATE intrinsic. location (input) Character array, by reference. The node name or environment ID indicating where the process to be killed is located. loclen (input) 32-bit integer, by value. The length in bytes of the location name. result (output) 32-bit integer, by reference. The error code returned; zero if no error. Description The RPMKILL intrinsic terminates a process that was created by RPMCREATE. It also deletes the remote environment if that environment was established by RPMCREATE. Any process on any node may call RPMKILL to kill a remote RPM process, as long as it has the correct program descriptor. To kill a process on your local node that utilizes another session, you must have configured the network for software loopback. To kill a local process in your session, you must be the creator of that process. The only required parameter is pd (option variable). The location and loclen parameters are also required in order to kill a remote process either if the remote process is independent or if the calling process is not the creator. RPM needs these to open a new connection to the remote node before killing the remote process. Use the RPMKILL intrinsic only to terminate perpetually running remote processes. Otherwise, use the "Shutting Down Sockets and Connections" procedure described in the NetIPC 3000/XL Programmer's Reference Manual. ADDOPT Adds an option entry to the opt parameter. Syntax ______________________________________________________________________ | | | ADDOPT (opt,entrynum,optioncode,datalength,data[,result])| ______________________________________________________________________ Parameters opt (input/output) Record or byte array, by reference. The opt parameter to which you want to add an entry. Refer to "Common Parameters" for more information on the structure of this parameter. entrynum (input) 16-bit integer, by value. Indicates which entry is to be initialized. The first entry is entry zero. optioncode (input) 16-bit integer, by value. The entry's option code, identifying the option. datalength (input) 16-bit integer, by value. The length (in bytes) of the data associated with the option. data (input) Byte array, by reference. The data associated with the option. result (output) 16-bit integer, by reference. The error code returned; zero if no error. Description The ADDOPT intrinsic specifies the values of an opt parameter's option entry fields and adds any associated data. The intrinsic also updates the size of the opt parameter . The parameter must be initialized by INITOPT before options are added by ADDOPT. Consider this program fragment: data_offset:=10; {10 bytes from beginning of data array] INITOPT (opt, 1); {one option entry} ADDOPT (opt, 0, 8, 2, {first entry is entry zero, option code 8; data_offset); entry's data area contains a 2-byte integer specifying an offset from data parameter address} IPCSEND (cd, data, dlen, , {sends data located at offset from data opt, result); address specified in opt} INITOPT and ADDOPT allow you to initialize the opt parameter for use in another intrinsic. These auxiliary intrinsics make the structure of the opt parameter largely transparent. Condition codes returned by ADDOPT are: * CCE--Succeeded. * CCL--Failed because of a user error. * CCG--Not returned by this intrinsic. This intrinsic may be called in split stack mode. INITOPT Initializes the opt parameter so that entries may be added. Syntax ___________________________________________________ | | | INITOPT (opt,eventualentries[,result])| ___________________________________________________ Parameters opt (output) Record or byte array, by reference. The opt parameter which is to be initialized. Refer to "Common Parameters" for more information on the structure of this parameter. eventualentries (input) 16-bit integer, by value. The number of option entries that are to be placed in the opt parameter. result (output) 16-bit integer, by reference. The error code returned; zero if no error. Description The INITOPT intrinsic initializes the length and number-of-entries fields (that is, the first 4 bytes) of the opt parameter. This must be done before options are added to the parameter by means of the ADDOPT intrinsic. Condition codes returned by this intrinsic are: * CCE--Succeeded. * CCL--Failed because of a user error. * CCG--Not returned by this intrinsic. This intrinsic may be called in split stack mode. OPTOVERHEAD Returns the number of bytes needed for the opt parameter in a subsequent intrinsic call, not including the data portion of the parameter. Syntax __________________________________________________________ | | | optlength := OPTOVERHEAD (eventualentries[,result])| __________________________________________________________ Parameters optlength (returned function value) 16-bit integer. The number of bytes required for the opt parameter, not including the data portion of the parameter. eventualentries (input) 16-bit integer, by value. The number of option entries that will be placed in the opt parameter. result (output) 16-bit integer, by reference. The error code returned; zero if no error. Description This function returns the number of bytes needed for the opt parameter, excluding the data area. The first parameter is required. Condition codes returned by this intrinsic are: * CCE--Succeeded. * CCL--Failed because of a user error. * CCG--Not returned by this intrinsic. This intrinsic may be called from split stack mode. RPM Program Examples The following two Pascal programs illustrate the use of the RPM intrinsics. The first program creates a new process (the second program) on a remote node. It also creates a remote session for the second program to run in. At the same time, it passes strings containing a socket name and a node name to the remote process. This information enables the second program to establish a connection to the first. In greater detail, the first program: * creates a call socket and names it; * reads the name of the node on which it is running; * initializes the opt parameter with strings containing the socket's name and the name of the node on which it is running; * creates a new process with the program name CREATURE on a remote node, passing the strings to the new process; * waits for a connection request from the remote process (and establishes the connection); * shuts down its call socket; * executes a loop in which it: * calls a procedure that receives a message by executing two IPCRECV loops. The first loop determines the incoming message length. The second loop receives data until all the pieces of the message have been received. * prints the message that was received; * receives a "last message" termination request; * sends a "termination confirmation message" in response to the termination request; * receives a result parameter value of 64 ("REMOTE ABORTED CONNECTION") in response to a receive request; * releases its VC socket. The execution of the second program is initiated by the first program. The second program: * obtains the socket name and node name passed by the creator; * uses these names to acquire a destination descriptor for the socket; * creates a call socket for itself, sends a connection request to the creator's socket, and establishes a connection to the creator process; * opens a data file; * executes a loop in which it: * reads a line of data from the data file; * stores the length (number of bytes) of the data in the first part of the message; * stores the data itself in the second part of the message; * sends the message on the connection, including the message length as the first two bytes of the message; * after all the data is transmitted from the data file, sends a "last message" that will be recognized by the receiving program as a termination request; * receives a "termination confirmation message" and shuts down the connection by releasing its VC socket.
NOTE Process Handling (PH) capability is required to use the following programs. Before running the first program, you must associate the remote node with the environment ID " REMNODE" via the DSLINE command. For example, issue the command DSLINE REMNODE=ASTRO if the remote node where the second program resides is named "ASTRO."
RPM Program 1 $standard_level 'HP3000', uslinit$ program creator (input,output); const maxdata = 2000; maxname = 20; type smallint = -32768..32767; datatype = packed array [1..maxdata] of char; nametype = packed array [1..maxname] of char; byte = 0..255; var calldesc : integer; result : integer; progname : packed array [1..15] of char; location : packed array [1..16] of char; login : packed array [1..25] of char; flags : packed array [0..31] of boolean; {32 contiguous bits} pd : packed array [0..15] of byte; destdescriptor : integer; vcdesc : integer; dlen : integer; i : integer; data : datatype; len : smallint; datastr : string[maxdata]; socketname : nametype; nodename : nametype; opt : packed array [1..50] of byte; {INITOPT and ADDOPT will structure the array for us} procedure terminate; intrinsic; {RPM and IPC intrinsic declarations} procedure ipccreate; intrinsic; procedure ipcname; intrinsic; procedure initopt; intrinsic; procedure addopt; intrinsic; RPM Program 1 (Continued) procedure rpmcreate; intrinsic; procedure ipcrecvcn; intrinsic; procedure ipcerrmsg; intrinsic; procedure ipcrecv; intrinsic; procedure ipcshutdown; intrinsic; procedure ipcsend; intrinsic; procedure leave(result: integer); var msg: string[80]; i, len, newresult: integer; begin ipcerrmsg (result, msg, len, newresult); if newresult = 0 then begin setstrlen(msg, len); writeln(msg); {print error message} end else writeln('IpcErrMsg result is ', newresult:1); terminate; end; procedure check ( result : integer); {error procedure} begin if result < > 0 then leave (result); {failed} end; {error handling procedure} {The following procedure receives one message that was sent via an ipcsend call. It assumes that the length (number of bytes) of the message was sent as the first 2 bytes of data and that the length value does not include those 2 bytes.} procedure receive ( connection : integer; var rbfr : datatype; var rlen : smallint; var errorcode : integer ) ; PRM Program 1 (Continued) const head_len = 2; type length_buffer_type = packed array[1..2] of char; header_len_type = record case integer of 0: ( word: smallint ); 1: ( byte: length_buffer_type); end; var i, j : integer; dlen : integer; header_len : header_len_type; tempbfr : datatype; begin { procedure receive } i:=0; errorcode := 0; while (i < head_len) and (errorcode = 0) do { get length of message } begin dlen := head_len - i; ipcrecv ( connection, tempbfr, dlen, ,, errorcode ); if errorcode = 0 then strmove(dlen, tempbfr, 1, header_len.byte, i+1); i := i + dlen; end; if errorcode = 0 then begin rlen := header_len.word; i := 0; while (i < rlen) and (errorcode = 0) do { get the message } begin dlen := header_len.word - i; ipcrecv ( connection, tempbfr, dlen, , , errorcode ); if errorcode = 0 then strmove(dlen, tempbfr, 1, rbfr, i+1); i := i + dlen; end; RPM Program 1 (Continued) end else rlen := 0; end; { procedure receive } begin {creator} {create call socket, then name it} ipccreate ( 3, 4, , , calldesc, result); {call socket, TCP protocol} check (result); {error procedure} socketname := 'MYSOCKET'; ipcname (calldesc, socketname, 8, result); check (result); {place rpmstring with socket information in opt parameter} prompt('What is the name of your local node? '); readln(datastr); len := strlen(datastr); strmove(len,datastr,1,nodename,1); fginitopt(opt, 2); {2 option entries} addopt(opt,0,20000,8,socketname); {option entry 0, rpmstring option code} addopt(opt,1,20000,len,nodename); {option entry 1, rpmstring option code} {create remote process and remote session; the program file CREATURE must exist in the logon group for VPRES.ACCNTG on the remote node} progname := 'CREATURE'; location := 'REMNODE'; login := 'VPRES.ACCNTG,PUB'; for i := 0 to 30 do flags [i] := false; {false=0, true=1 for each bit in array} flags [31] := true; {set dependent flag} rpmcreate (progname,8,location,7,login,14, , ,flags,opt,pd,result); if result < > 0 then begin writeln('RPM ERROR # is ',result); terminate; end; RPM Program 1 (Continued) {wait for connection request from remote process} ipcrecvcn (calldesc, vcdesc, , , result); check (result); ipcshutdown (calldesc); {receive messages on connection and print them; repeat until 'END' message received} repeat begin receive (vcdesc, data, len, result); check (result); setstrlen(datastr, len); strmove(len, data, 1, datastr, 1); if datastr < > 'END' then writeln (datastr); {print data received} end until datastr= 'END'; writeln('END received'); data := 'Y'; {shutdown procedure} ipcsend ( vcdesc, data, 1, , , result ); check (result); receive ( vcdesc, data, len, result ); if result = 64 then ipcshutdown( vcdesc ) else check ( result ); end. {creator} RPM Program 2 $ standard_level 'HP3000', uslinit$ program creature(datafile); {"datafile" must be an already existing file} const maxdata = 2000; maxmsg = maxdata + 2; maxname = 20; maxloc = 20; type byte = 0..255; shortint = -32768..32767; datatype = record len : shortint; msg : packed array[1..maxdata] of char; end; nametype = packed array[1..maxname] of char; loctype = packed array[1..maxloc] of char; var datafile : text; rpmstringlen : integer; socketname : packed array [1..16] of char; nodename : packed array [1..16] of char; destdesc : integer; calldesc : integer; vcdesc : integer; result : integer; data : datatype; strdata : string[maxdata]; socknmlen : integer; nodenmlen : integer; y_data : char; y_len : integer; procedure terminate; intrinsic; RPM Program 2 (Continued) {RPM and IPC intrinsic declarations} procedure rpmgetstring; intrinsic; procedure ipcerrmsg; intrinsic; procedure ipclookup; intrinsic; procedure ipccreate; intrinsic; procedure ipcconnect; intrinsic; procedure ipcrecv; intrinsic; procedure ipcsend; intrinsic; procedure ipcshutdown; intrinsic; {error handling procedure} procedure check (result : integer); {error procedure} begin if result < > 0 then terminate; {failed} end; begin {creature} {get the creator process's socket name and node name, one at a time, from the rpmstrings} rpmstringlen:= maxname; rpmgetstring (socketname, rpmstringlen, result); socknmlen := rpmstringlen; strmove (socknmlen, socketname, 1, strdata, 1); rpmstringlen := maxloc; rpmgetstring (nodename, rpmstringlen, result); nodenmlen := rpmstringlen; setstrlen(strdata,0); strmove(nodenmlen, nodename, 1, strdata, 1); {look up socket name to get destination descriptor} ipclookup (socketname,socknmlen,nodename,nodenmlen,,destdesc, , ,result); check (result); {error procedure} {create a call socket for this process} ipccreate (3, 4, , , calldesc, result); {call socket, TCP protocol} check (result); {send a connection request to the creator process and receive the creator's reply to complete the connection} RPM Program 2 (Continued) ipcconnect (calldesc, destdesc, , , vcdesc, result); check (result); ipcrecv (vcdesc, , , , ,result); check (result); ipcshutdown (alldesc); ipcshutdown (destdesc); {send messages on connection} { prompt for messages and send them } reset(datafile); {open input file} while not EOF(datafile) do begin setstrlen(strdata, 0); readln(datafile, strdata); {read message} data.len := strlen(strdata); {store message length} strmove(data.len, strdata, 1, data.msg, 1); {store message} ipcsend(vcdesc, data, data.len+2, , , result); {send message, including length as first 2 bytes} check(result); {failed} end; {connection shutdown procedure} data.len := 3; data.msg := 'END'; {termination request} ipcsend(vcdesc, data, 5, , , result); check(result); y_len := 1; ipcrecv (vcdesc, y_data, y_len, , , result); if (y_data = 'Y') and (result = 0) then ipcshutdown(vcdesc) else check(result); end. {creature}