The STRING Macro Instruction for S/370 and S/390 Assembler

[Home] [Products] [Support] [Documents] [Partners] [Contact Us] [Search] [Freeware]

The STRING assembler macro instruction provides functionality similar to the COBOL DISPLAY or PL/I PUT EDIT instructions. STRING can be used in environments which support Assembler H or the High-Level Assembler, i.e. MVS, OS/390, z/OS, VSE/ESA, z/VSE and VM/CMS. MVS users may obtain the STRING macro from the freeware section of this Web site. VSE and VM users should contact us to obtain the STRING macro.

Using STRING, the programmer can concatenate any number of fields and constants, convert each of them to printable format if necessary, and store the result in the specified output area. STRING is designed for easy implementation in re-entrant and non-reentrant programs. In particular, STRING uses the second half of the standard save area supplied by the caller for data editing, and does not require a separate work area.

The STRING macro requires Assembler H (with or without the SLAC Mods), or the High-Level Assembler and only supports AMODE=24 and AMODE=31 programs. However, there are two alternative versions of the macro that provide the same functional capabilities in different environments:

STRING64 supports AMODE=64 programs in z/OS. STRING64 is distributed in file 492 of the CBT tape.
STRINGXF is compatible with the Assembler XF on OS/VS systems. STRINGXF is distributed in the OSVS238J package on this site.

Syntax

The syntax of the STRING macro is described below. Coding examples are available later in this document.

     (1) label  STRING {field_specification1}
                      {,field_specification2}...
                      ,INTO=output_area|(output_area,length)
                      {,PRINT=GEN|NOGEN}

     (2) label  STRING GENERATE
                      {,PRINT=GEN|NOGEN}

field_specification

Each field to be printed is described as a positional operand. Each operand specifies the field address, its length, and its formatting requirements.

Four field description formats are supported:

symbol
(symbol,length,format)
(d(r)|(r),length,format)
((r),,format)
'character string'

Symbol specifies the field address. It must be an S-type (relocatable) address.

d(r) may be used to specify the field address in S/370 base-displacement format. If d is zero, it may be omitted. If d(r) or (r) is used, length must also be specified. R14 and R15 may not be used. If d(0) is used, it is handled the way the assembler does, i.e. R0 as a base register is assumed to contain zero: 16(0) is equivalent to 16, CVTPTR or, X'10'.

((r),,format) specifies that (r) contains the value itself, not an address. R14 and R15 may not be used.

'character string' specifies a literal enclosed in single quotes as specified in a DC instruction. Hex strings or character strings are supported. The following expressions are equivalent: 'ABC' C'ABC' X'C1C2C3'

Length specifies the length and/or the type of the input field. It may be specified as an integer, a symbol, a register, or a constant. When used with symbol, it overrides the assembled length and/or type. Length is required if field is specified as d(r) or (r). If a zero length is specified, the field is ignored. Length can be specified as follows:

nn field length in bytes
H half-word
F full-word
FL1 1-byte binary integer
FL3 3-byte binary integer
P packed field
(r) length of character string (R0 thru R12)
d(r) length of character string (R1 thru R12)

Notes:

If the field address is specified as a symbol that has been defined previously in the program, the symbol type is known and there is no need to specify it.
If the length is specified as (r) or d(r) and the value is greater than the address itself, (r) or d(r) is considered to be the end address +1 instead of the length.
The length is not specified for packed fields. The @STRING subroutine scans the field left-to-right until it finds a byte with a valid sign in the low-order 4 bits.
If symbol is an arithmetic expression and no length is coded, the implicit length will be that of the first symbol in the expression; for example, if symbol is coded as PSATOLD-PSA, then the implicit length will be L'PSATOLD.
All numeric items are assumed positive.

Format optionally indicates editing options that must be applied to a field.

	L	left justified
	R	right justified
	nn	output length
	0	adjust length
	Z	leading zeroes
	B	leading/trailing blanks
	T	truncate character string after last non-blank
	X	display in hexadecimal
	YYMMDD	convert julian date to YYMMDD
	YY/MM/DD convert julian date to YY/MM/DD
	DD/MM/YY convert julian date to DD/MM/YY
	MM/DD/YY convert julian date to MM/DD/YY
	YYYYMMDD convert julian date to YYYYMMDD
	YYYY-MM-DD convert julian date to YYYY-MM-DD

The default format depends on the field type:

	Type			  Default Format

	character string		L
	FL1				R3B
	H or FL2			R5B
	other numeric fields		R7B

Note: L0 and T are equivalent for character strings.

'character string' is any character string enclosed in single quotes. Blank spaces may be specified as nnX, where nn is the number of X'40' bytes you want to be inserted in the output line. On MVS systems, %TIME may be specified to obtain the current time in hh.mm.ss.hh format. On VSE systems, %TIME may also be specified if the TIME macro is available, as is the case on VSE/ESA 2.4 and above; if the TIME macro is not available, the STRING macro must be modified to replace TIME with GETIME.

INTO=output_area|(output_area,length)

INTO indicates the address and length of the output area into which the result of the concatenation should be placed (left justified). If the output area is too small, truncation will occur. If it is too large, it is padded with blanks.

The address may be a symbol, d(r) (S-type address) or (r).

The length may be specified as an integer, a symbol, a register, or a constant; it is required if the address is coded as d(r) or (r). If length is not specified for a symbol-type address, the assembled length of the symbol is used.

Upon return from STRING, R15 contains the length actually used in the output area (before padding).

PRINT=GEN|NOGEN

This operand is used to temporarily override the current assembler PRINT specification with the specified value (GEN or NOGEN).

GENERATE (format 2)

The GENERATE format must be specified once at the end of the program. It generates the @STRING sub-routine as well as all the literals specified in previous invocations of the macro.

The GENERATE format allows the specifications of the AR_MODE, NO_CSECT and LOCTR options.

	STRING GENERATE<,AR_MODE>,LOCTR>>>
			NO_CSECT

The following combinations are valid:

	STRING GENERATE
	STRING (GENERATE,NO_CSECT)
	STRING (GENERATE,AR_MODE)
	STRING (GENERATE,,LOCTR)
	STRING (GENERATE,AR_MODE,LOCTR)

The AR_MODE option can be specified to generate a @STRING module that supportd AR mode. Example:

	STRING (GENERATE,AR_MODE)

The NO_CSECT option can be specified to indicate that the @STRING module should not be generated; only the literals are generated in this case. Example:

	STRING (GENERATE,NO_CSECT)

The @STRING CSECT contains optional functions (such as %TIME or julian date conversion) that are only generated if they have been specified in the previous invocations of the STRING macro.

To generate an @STRING CSECT that supports all of the optional functions, two STRING GENERATE macros must be specified:

	STRING (GENERATE,NO_CSECT)        Generate Literals
	STRING GENERATE                   Generate full-function CSECT

Examples:

	STRING 1X,INTO=BLANKS		blank out the BLANKS area
	.	.
 BLANKS DS    CL10000

	STRING 'ERROR===>',LINE1,'<=== POS ',((R6),,L0),INTO=output_area

	STRING 8X,C'ERRORS FOUND: ',(ERRORS,,L0),INTO=(4(R7),44)
	ST    R15,0(,R7)		store length

	STRING 'CVT ADDR IS ',(CVTPTR,4,X),X'40C1C2C3C4',		X
	      INTO=LINE

	LA    R5,WORK+16		end addr +1
	STRING 'R4=',((R4),,X),INTO=(WORK,(R5)),PRINT=GEN

	STRING '//JOBLIB DD DSN=',(DSN1,,T),',DISP=SHR',INTO=((R2),72)

	PUT   SYSLIN			PUT Locate
	LH    R0,SYSLIN+82		LRECL
	STRING '   NAME  ',(4(R3),8,T),'(R)',INTO=((R1),(R0))

	STRING GENERATE 		Generate literals and sub-routine

Programming Notes

A STRING macro generates only 6 bytes that need to be covered by base registers. More code is generated at the end of the current CSECT (using LOCTR pseudo instruction), but this code does not require addressability. This is particularly useful when STRING calls specify a large number of literals.
Additionally, STRING does not use A-type constants (ACON), but S-type constants (SCON) which require symbols to be addressable at the point in the program where STRING is issued.
While these addressing techniques reduce the number of base registers required to cover the program's code and make it easier to write reentrant programs, they will produce assembly errors in the following situations:
1. STRING is used in more than one CSECT in the same assembly
2. the CSECT in which STRING is used is longer than 64K
3. symbols are not addressable at the point in the program where STRING is issued
4. the $STRING symbol (generated in the $LTORG LOCTR during the GENERATE invocation of the STRING macro) is not addressable in some of the STRING calls.
  
  Search key-words: ibm 370 390