Writing $Functions with Your Own Error Messages - Rocket Software

Writing $Functions with Your Own Error Messages
A Newsletter Excerpt for Model 204 Users
April 2009
USE OF AND ACCESS TO PRODUCTS AND FEATURES ARE IN ACCORDANCE WITH THE TERMS AND
CONDITIONS OF THE USER’S SOFTWARE LICENSE. THE PRESENTATION OF MATERIAL HEREIN DOES NOT, IN
ANY MANNER, MODIFY SUCH TERMS AND CONDITIONS.
Writing $Functions with Your Own Error Messages
By James Damon
In the February 2009 issue of Rocket M204, I showed you how to write your own
$function in IBM Assembly Language, assemble that $function in the FUNU control section,
and link-edit FUNU into the Model 204 nucleus using ONLINE or BATCH204 load
modules. Once that is done, you can call your $function from User Language to perform
special processing. The example I provided, $INSCHAR, however, was incomplete. It
had no error detection or error reporting facilities to indicate to the user that an input
value to the $function was incorrect. In this article I will show you how to add your own
error messages to the MSGU control section, then assemble and link-edit that control
section into the Model 204 nucleus.
MSGU Control Section
As with the source listing for the FUNU control section, the MSGU control section is also
found in MACLIB, which is distributed with each release on the Model 204 installation
tape. It is probably named something like M204.rlse.MACLIB, where rlse=V710, V610 or
V510. I will not reprint the entire source listing for MSGU here, just the part that involves
defining user error messages:
ESTRT USER=YES,PREFIX=USER
* REPLACE THIS DUMMY MESSAGE WITH ONE OR MORE USER MESSAGES
EDEF 1,0000,I,,,'DUMMY MESSAGE' **********
For the $INSCHAR function, I’ve added the following two error messages (in blue):
ESTRT USER=YES,PREFIX=USER
* REPLACE THIS DUMMY MESSAGE WITH ONE OR MORE USER MES-
SAGES EDEF 1,0000,I,,,’String length must equal 10 bytes’
EDEF 2,0000,I,,,’String must be numeric 0-9’
Rocket M204 April 2009 1 of 4

Writing $Functions with Your Own Error Messages
In the $INSCHAR source listing, I have added code to test the string argument to
enforce those two rules:
1) The argument must be exactly 10 bytes
2) The argument must be numeric: digits 0-9
The Modified $INSCHAR Code
The blue lines of code below were added to implement error checking.
**$INSCHAR Receives a numeric character string (ARG1) of length 10
* and returns that character string with the single
* character (ARG2) inserted in col 4 and col 7 of ARG1.
* Col: 4 7
* | |
* v v
* ARG1: 1234567890
* ARG2: _ (DEFAULT)
*
* RETURN: 123_456_7890
$INSCHAR ENTER
MVC BUF2(1),INSDEFC Get default character for insert
ARG 2,NOARG=INSDEF If ARG2 not provided, use default
L R2,4(X1) Type of ARG - required for RTSTRL
CCALL RTSTRL Call ReTurn STRing with Length
* Returns A(ARG2)-1 in R1 and len in R2
MVC BUF2(1),1(R1) Move ARG2 (char for insert) to BUF2
INSDEF ARG 1,NOARG=INSDONE If ARG1 not provided, return null
L R2,4(X1) Type of ARG - required for RTSTRL
CCALL RTSTRL Returns A(ARG1)-1 in R1 and len in R2
C R2,=F'10' Is length of ARG1 exactly 10 bytes?
BNE INSERR1 No, issue error
* Ensure ARG1 is numeric only
MVC BUF1(10),1(R1) Move ARG1 to BUF1
L X1,KAPFF A(KZFF) = 256 foxes
MVC KAJUNK(256),0(X1) Setup table for Translate and Test
MVC KAJUNK+C'0'(C'9'-C'0'+1),KA00 Get zeroes for numbers
BCTR R2,0 Subtract one from length
EX R2,$INSNUM TRT BUF1(0),KAJUNK
IF BNZ If non-numeric character found
ERROR 2,OPT=USER String must be numeric 0-9
B INSDONE Set len of ret string to 0 and return
IFEND
LA R2,10 Get len back in R2
MVC BUF1(20),KA00 Clear BUF1
MVC BUF1(3),1(R1) Move 1st 3 chars of ARG1 to BUF1
MVC BUF1+3(1),BUF2 Insert ARG2
MVC BUF1+4(3),4(R1) Move next 3 chars of ARG1 to BUF1
MVC BUF1+7(1),BUF2 Insert ARG2
S R2,=F'6' Subtract (3+3) bytes from ARG1 length
EX R2,$INSMVC Move rest of ARG1 to BUF1
A R2,=F'8' Get new len of ARG1(6+2+rest of ARG1)
LA R1,BUF1-1 Get A(BUF1) minus 1
B INSRET
INSERR1 ERROR 1,OPT=USER String length must be 10 bytes
INSDONE SR R2,R2 No ARG1, set return string len to 0
Rocket M204 April 2009
2 of 4

Writing $Functions with Your Own Error Messages
INSRET LEAVESTR Return the new string or null
INSDEFC DC C'_' Default character for insert
$INSNUM TRT BUF1(0),KAJUNK TRT to detect non-numeric data
$INSMVC MVC BUF1+8(0),7(R1) Remainder of ARG1 starting column 7
LTORG
EJECT
Assemble and Link-Edit Both FUNU and MSGU
After you have updated the FUNU and MSGU source listings in the Model 204 macro
library, M204.rlse.MACLIB, you can use the FUNUASM and MSGUASM jobs in the
JCLLIB dataset to reassemble those control sections and place the new object decks in
M204.rlse.OBJLIB. Remember, however, that you must set these options to ‘Y’ in
INSPARMS during the installation process, or the FUNUASM and MSGUASM jobs will
not be created:
FUNC-USER=Y ** Enable USER-WRITTEN functions
MSG-USER=Y ** Enable USER-WRITTEN messages
Following successful assembly, the M204RLNK or similar job can be used to link those
two control sections from M204.rlse.OBJLIB into the ONLINE and BATCH204 load
modules.
Testing $INSCHAR
The following examples show the results with the error checking code and the new error
messages assembled into MSGU. In the first example the procedure supplies the
telephone number to $INSCHAR as a literal.
BEGIN
PRINT $INSCHAR('7814666601','.')
END
INCLUDE 0
781.466.6601
Rocket M204 April 2009
3 of 4

Writing $Functions with Your Own Error Messages
In this next example the procedure retrieves three telephone numbers from three
different records in a Model 204 database and passes them to $INSCHAR from the field
TELNO.
BEGIN
FR WHERE TELNO IS LIKE *
PRINT
PRINT TELNO
PRINT $INSCHAR(TELNO,'-')
END
INCLUDE 0
800755422
*** USER.0001: String length must equal 10 bytes
3037868%62
*** USER.0002: String must be numeric 0-9
8005551212
800-555-1212
MSGCTL Command for User Messages
The MSGCTL command can be used to change the default action taken when a userdefined
message is issued just as it can be used to change that action for Model 204
defined messages. If you need a CCASNAP to be generated when one of your error
messages is issued, you may want to use the MSGCTL command like this:
MSGCTL USER.0001 SNAPPDL
See the description of the MSGCTL command in the Model 204 Parameter and
Command Reference for further details.
Summary
Without error checking we really did not have a useful $function. Now that we have
added the appropriate error messages and error checking code, we have a complete
$function. It inserts a separator into a character string of numbers and it also can detect
and report errors in that string.
Rocket M204 April 2009
© 2009 Rocket M204
77 Fourth Avenue, Waltham, MA 02451
4 of 4