Skip to main content

IBM Systems  >   z Systems  >   z/VM  >  

Description of RXSERVER

Download count: 17 this month, 4439 altogether.

Downloads for RXSERVER:
VMARC archive: v-884K

From Kris Buelens, IBM Belgium
change history

Many servers need some common functions, such as the capability to execute commands at given times.  To make it easier to maintain the common functions as well as to ease the creation of new servers, the common part is stored in a separate CMS file, the SERVER KERNEL.  Another CMS file contains the functions specific to each server.  This server-specific file is named fn IEXEC.  The procedure GENSERV will combine both files to make an executable REXX program to be run inside the server.  Examples of server machines we built around this kernel are VMPRF and VMUTIL.

The standard functions of the kernel are quite elaborated.  The kernel

  • uses a WAKEUP  file to allow command execution at certain times or days
  • checks authorization for command or files sent to it
  • executes commands sent by authorized end-users and returns the response
  • uses an external control file with run-time parameters (such as authorizations)
  • receives new code and automatically restarts itself
  • maintains several versions of code for easier rollback
  • handles midnight special processing
  • recovers REXX coding abends (restarts itself, but avoids a restart loop)
  • allows dynamic update of entries in the WAKEUP file
  • interfaces with DOME and GEEFME tools (these tools make it easier to collect command responses from multiple VM systems and compare the results)
  • avoids message-wars between servers
  • has a standard logging, notification of logged errors and automatic disk cleanup
  • etc.

Version 4.6   23 Apr 2003

Version 4.6 of this kernel is the first version we make available on VM's WWW download lib.

Version 5.0   17 Feb 2004

  • New keyword in PROFILE file LogOnlyUsers : simply log msgs they send.
  • New keyword in PROFILE file NOBackupClasses : allows to decide at SENDFILE time no backup must be taken.
  • The RESTART command honors the setting of the CanRestart variable unless you use RESTART FORCE.
  • The reLINK/reACCESS process for mdisks listed on DISK profile records has been redesigned.  The new server command MAINTain/REFResh DISks/MAChine to force this reLINK/reACCESS process at any time.
  • Provisions for the upcoming CHKSERV CMS/GUI application.
  • When the REXX logic handling WAKEUP file events logs more than one message, the WAKEUP file record will no longer be placed multiple tiles in the message log.
  • An error message is displayed when the PIPE reading the server's PROFILE fails due to bad pipeline stages.  Before V5, this happend in silence.
  • Changes to the LOGMSG subroutine: args 4 to 20 can be messages to log too; it has been made easier to change the severity of the message(s) to log.
  • Commands sent with the MIXED prefix (to have them in mixed case) were executed with ADDRESS CMS, what caused them to be uppercased again.
  • WAKEUP file entries for dates in 19xx were never purged
  • Add undocumented commands/command options to support the ADDON and DELON XEDIT prefix command to tailor the server's WAKEUP file.
  • Some important "exit points" are now placed as before standard kernel code.  This allows you to override standard kernel commands.
  • The TAG record of reader files is stored in REXX variable TAGDATA so that your exit code can extract other information than we need.

Version 5.1   dated 8 April 2004

  • Avoid turning off heartbeat when a long command runs over midnight.
  • Pressing "enter" alone is no longer enough to end server.  Hence an accidental CP SEND server xxxx" won't harm either.  A new subroutine handles console interrupts and defines some "standard" console commands: STOP, RESTART, or CMS xxxx are already in the code.
  • "Server"-class commands can now set their return code in variable SrvCmdRc.  This way, "server" commands responses will honor the "NOMSG", or "EMSG" prefix keywords.
  • The ADDON XEDIT macro had a bug.
  • Addition of the "Adding new commands" section to the RXSERVER HTML document.

Version 6.3   dated May 2006

The important enhancements are all described in the documentation: RXSERVER HTM.

First the major changes and new functions.

  • Complete re-arrange of the Command Analyzer and Auth Checks.  Affects programmers only, doesn't bring new function but avoids programming mistakes.  See RXSERVER MIGRATE.
  • Message FORWARD feature.  Based on "server PROFILE" records, messages of certain classes can immediately be forwarded to some users by a MSG, e-mail, ...  Also server start-up problems can be forwarded directly to support people.
    The LOGMSG subroutine now recognizes "multiline messages", what is important when messages are forwarded in an e-mail: all messages of a "multiline message" are sent in a single e-mail.  The extra lines are passed as REXX arg(4) to arg(20) to LOGMSG.  A new LOGMSG_STRING subroutine was created where you use X'15' as newline separator.
  • A new LOGMSG server command allows other severs to put a line in the log file.  This is meant for "sub-servers" that get their work from an RxServer to store their result in the log file.  The maximum length is limited by CP: about 132 if SMSG is used, about 229 if CP MSG is used.  Multiline messages are impossible.
  • External EXECs called by the main, kernel based, server EXEC often want to write messages to the server's log file.  They obviously can use EXECIO and directly write to the log, but these messages will never be forwarded as the kernel code doesn't see them.  The architected solution we provide: the external exec should place their messages in the IPC queue we provide; x'15'x can be used a newline character.
  • A new RESPONSE prefix option allows the console messages of commands be sent to another VM user than sender of the command.
  • A new LOGCONS prefix option allows the console messages of commands stored in the server's WAKEUP file to be logged in the server's log file in case of failure.  The number of logged messages is limited by LogConLimit.
  • Recognize CP QUERY and CP INDICATE as general user cmds.  That is: anyone can issue "TELL server QUERY xyz" as well as "TELL server CP QUERY xyz".
  • A RUNONCE EXEC can be sent & is executed once automatically.  It provides a shorter way to perform "SENDFILE some EXEC myserver", "TELL myserver ASME EXEC some", and "TELL myserver CMS ERASE some EXEC".
  • If you get the SHUTTRAP package all RxServer based servers will gracefully stop when they get a Shutdown Signal.  If you don't want the server to stop for a Shutdown Signal and you have've got the SHUTTRAP package: change some REXX variable in the INITIALIZE routine.
  • The new console 'LOGOFF' command performs a clean stop.
  • New keywords in "server PROFILE" and corresponding handling:
      IgnoreMSGs IgnoreSMSGs IgnoreRDRs PurgeRDRs
    to selectively ignore messages, SMSGs or RDR files
  • New BackupClasses keyword in "server PROFILE" defines a spool class for which will surely keep a backup copy of the file sent. Default is class B.
  • New HoldClasses keywword in "server PROFILE" defines spool classes for which the server will not automatically receive the file sent.  You can then send your own RECEIVE command.  No class is defined by default.
  • Version flags in Server PROFILE allow to code keywords that are ignored when the server is running older levels of the kernel or your code.  Refer to the RXSERVER MIGRATE file.
  • We learned how we can avoid that pending messages sent with "SMSG server xxx" interfere with VMCF based commands like NETSTAT, and RAC.  The kernel now uses "CP SET SMSG IUCV" and we removed SMSG from the WAKEUP options.  An example of the problem (that is now fixed):
    An EXEC contains "CP SM server CMS RAC PERMIT mdisk1 ..." and "CP SM server CMS Q DISK A".  In practice chances are high that when the server executes the first RAC command, the second SMSG is already queued in the server's VMCF queue.  The RAC command also uses VMCF to talk to RACFVM, and RAC will display the pending SMSG ("CMS Q DISK A" in this example) as part of the RAC response. 
    NETSTAT is a bit different: it throws away all pending SMSG's.
    An SMSG coming in while these commands run can even end in a CP READ status.

Now small changes, and bug fixes

  • When the server got A-disk full (what makes using a WAKEUP file impossible), the server will start using the WAKEUP file again when it finds the A-disk is no longer full.  In practice someone needs to send it some command that erases some file(s).
  • Don't abend in free-space check if A-disk is SFS.  But, we consider running an RxServer with its A-disk in SFS unwise: if the SFS server would go down, your RxServer gets into trouble.
  • When adding or changing commands to the WAKEUP file, we better check the validity of date and time and strip leading spaces from the command.
  • At midnight, old backup files are deleted.  The code simply removed all backup files "backupDays" days older than the date of the base file.  This simple logic didn't work well:
    • Backup files whose timestamp differs less than "backupDays" with the base file were kept.
    • But, when you send a new version after a long period without changes, at midnight all backup files got erased.
    Now we keep the first backup as long as the base file isn't "backupDays" days old.  Other backups are erased as soon as they are "backupDays" old.  Note: we don't keep track of the arrival date of a file; the logic is based on the LISTFILE's timestamps.
  • We no longer will run log cleanup during INIT event, this to avoid novalue problems and alike.
  • The options used on the WAKEUP command can be overridden in the kernel's exit point for the INITIALIZE routine.
  • When you send a PIPE command to the server, we will no longer append one extra blank to the command.
  • The lrecl of the kernel is kept below 81 characters to avoid problems with our z/OS ChangeMan friends.
  • The CMS stack is cleaned at start & midnight (in the Maintain_Machine routine).
  • The "owner" defined in the "server PROFILE", which will be default to report problems to, can now also be an SMTP address.  But only if MAILIT is available.
  • The $$REXX$$ command will now tell you when there was a syntax error instead of "Rexx interpretion ended fine".
  • Server version logged at Syntax&Novalue errors and Startup.
  • If Syntax or Novalue happens during handling RDR file: we place the file in HOLD, this to avoid a server looping on a reader file that causes problems.
  • We improved the checks for the minidisks listed on DISK records in "server PROFILE".  When minidisk addresses are swapped.  An example: you swap addresses of MAINT 193 with MAINT 493, and you LINK MAINT 493 111.  You surely get what now is MAINT 493, but what previously was known as MAINT 193.  But, when before the swap, some links existed to MAINT 193, a Q MDISK 111 still tells your 111 is MAINT 193.  We fixed this by not checking the owner id, but the mdisk location; VMLINK has been fixed with VM63910.

Version 6.4   dated 9 June 2006

As we found two nasty bugs in new 6.3 function, version 6.4 was quickly created with these fixes and some other improvements that were sitting on my whishlist.

  • External execs can store messages to add to the server's log file in an IPC queue.  By an oversight, we could not extract messages longer than 257 chars; if the first one was longer, it and all other entries in the IPC queue were never processed.
  • When a server was restarted and the IPC queue contained a msg to be logged (rc=77), the server abended with "unexpected WAKEUP rc=0"
  • Output of QUERY & INDICATE commands coded in the WAKEUP file was not included in server spooled console.  Similar for any WAKEUP file commands that used the LOGCONS prefix.
  • When a reader file caused a disk full, the server often lost its ability to use the WAKEUP file.  Now when RECEIVE fails we erase the receive work file, what most probably removes the disk full again, before WAKEUP encounters problems.
  • RECEIVE with disk full also often caused that RECEIVE's error message could not be logged.  We fixed this too.  Failing receives should no longer remain unnoticed.
  • When RECEIVE failed, post-processing REXX logic was still executed (post-processing is for example an EXECDROP and EXECLOAD for execs that are loaded in storage).
  • The SAVE option on the TRACE command is now documented.
  • The GENSERV EXEC has an option to allow you to build servers with another level of SERVER KERNEL. For example
  • Document the Shutdown interface based on SHUTTRAP; describe some things to reflect about if your server uses SFS directories.

Version 6.7   dated 31 October 2013

Please refer to RXSERVER CHANGES