SAP SCRIPT CONTROLS

SAPscript Control Commands

The functionality of the SAPscript editor is made available through a set of commands which the user selects either from the menu or via the function (F-) keys. These commands give you full editing control over your text. They are executed immediately when called.


There is, however, another kind of SAPscript command, namely the control commands. The purpose of these is to allow control of the output formatting. These commands are not interpreted by the SAPscript editor, but are passed through to the SAPscript Composer for processing.

The Composer is the program that converts text from the form displayed in the editor to the form used for printing. This includes, for example, line and page formatting, the replacement of symbols with their current values and the formatting of text according to the paragraph and character formats specified.


The SAPscript control commands are described in the following sections.

The Syntax of Control Commands
Explicit Page Break: NEW-PAGE
Preventing Page Breaks: PROTECT
Next Main Window: NEW-WINDOW
Assigning a Value to a Text Symbol: DEFINE
Formatting Date Fields: SET DATE MASK
Formatting Time Fields: SET TIME MASK
Country-Dependent Formatting: SET COUNTRY
Position of the Leading Sign: SET SIGN
Initializing Numbered Paragraphs: RESET
Including Other Texts: INCLUDE
Changing the Style: STYLE
Formatting Addresses: ADDRESS


Setting a Header Text in the Main Window: TOP
Setting a Footer Text in the Main Window: BOTTOM
Conditional Text: IF

The CASE command
Calling ABAP/4 Subroutines: PERFORM
Inserting Print Controls: PRINT-CONTROL
Boxes, Lines, Shading: BOX, POSITION, SIZE
Hexadecimal Data: HEX, ENDHEX
Summing a Program Symbol: SUMMING


The Syntax of Control Commands

SAPscript control commands are entered and edited in the text editor in the same way as a normal line of text. They do, however, differ from normal lines of text in respect to the following points:

• The paragraph format /: must be entered in the format column to identify a control command.
• You enter the command itself in the text line. You will notice that all key words and other parts of the specification not given as literal values enclosed in apostrophe characters are automatically converted to capital letters.
• A control command, together with any parameters it requires, may not occupy more than a single line.
• A maximum of one control command may appear in each line.
• The editor formatting has no effect on lines containing control commands.



If a control command is unknown or it contains syntax errors, the line containing it will be treated as a comment line. It will be neither interpreted nor output.


Explicit Page Break: NEW-PAGE

SAPscript automatically inserts a page break when the main window of a page (MAIN) is full. You can use the NEW-PAGE command to force a page break in the text at any point you want one. The text following this command will appear on a new page. The page break will always be performed (it is an unconditional page break).


The NEW-PAGE command completes the current page. This means that all the windows that are still on the page will be output immediately. If you use the NEW-PAGE command without parameters then the page defined in the layout set for the current page as the next page will be taken next. If, however, your layout set contains a number of different pages then you can specify any one of these as the next page to be used.


Syntax:
/: NEW-PAGE [page_name]

/: NEW-PAGE
The current page will be completed and the text in the following lines will be written to the page specified in the layout set.
/: NEW-PAGE S1


As above, except that the page S1 will taken as the next page.

• If a page not contained in the layout set is specified in a NEW-PAGE command then this specification is ignored.
• You should take care that there is not an blank line immediately before a NEW-PAGE command. This would serve no useful purpose and may lead to an unexpected blank page being printed. This would happen if an implicit page break would normally occur within the blank line.



Preventing Page Breaks: PROTECT


You can specify either in the style or in the layout set that a particular paragraph should not be split in two by a page break. If the page protect attribute is set then the complete paragraph is always output on a single page. This property applies only to that particular paragraph.


This attribute is not intended to be used to protect all paragraphs against a page break. The point is that a page break is by its very nature a dynamic event and the exact point at which it occurs depends on the current state (length and contents) of the preceding text. It is also possible that one may want to protect only certain parts of a paragraph against a page break.

In principle one could achieve this through the use of the NEW-PAGE command immediately before the text concerned. Explicitly beginning a new page at this point should ensure that a further page break does not occur within the text. However, this technique is not change-resistant.

Assume, for example, that you have formatted your text with the help of the NEW-PAGE command such that no page breaks occur where they should not, and that you now insert some new lines or delete some existing lines. These changes will cause all the subsequent text to be moved relative to the printed page, and you will therefore need to check each NEW-PAGE command you had previously inserted to see if it is still in the correct place.

SAPscript provides the PROTECT .. ENDPROTECT command pair to allow you to define the areas to be protected against a page break on an individual basis. If you enclose the text to be protected in these commands, then SAPscript will ensure that each line of this text is printed together on the same page.

If the complete text fits in the space remaining on the current page, then it is output on that page just as it would be if no PROTECT command had been used. If, however, the remaining space is not sufficient for the text, then the PROTECT command has the same effect as a NEW-PAGE command and text is printed on a new page.


Thus the PROTECT/ENDPROTECT commands may be regarded as a kind of conditional NEW-PAGE command, the condition being whether or not the lines enclosed between the two commands fit in the space remaining in the current main window.


Syntax:
/: PROTECT
:
:
/: ENDPROTECT

The text lines to be protected are enclosed between the two commands.

• An ENDPROTECT command without a preceding PROTECT command has no effect.
• If the terminating ENDPROTECT is missing, then it will be assumed at the end of the text.
• PROTECT .. ENDPROTECT command pairs cannot be nested. If a second PROTECT command occurs before the first one has been terminated by an ENDPROTECT, it will be ignored.


• If the text enclosed by a PROTECT .. ENDPROTECT pair is itself too long for a single page, then a page break is generated immediately before the text and the text is output in the normal way. It is then unavoidable that a page break will occur at some point within the text.


Next Main Window: NEW-WINDOW

Each page can consist of up to 99 main windows. Each main window is assigned a consecutive identifying number (0..98), and the windows are filled in this order. This feature enables SAPscript to print labels and to output multi-column text. When one main window fills up, the next main window on that page is taken, if there is a next one. A page break is inserted after the last main window.


You can use the NEW-WINDOW command to call the next main window explicitly, even if the current main window is not yet full. If you are in the last main window of the page, the command has the same effect as the NEW-PAGE command.


Syntax:
/: NEW-WINDOW



Assigning a Value to a Text Symbol: DEFINE

Text symbols acquire their values as a result of explicit assignment. This assignment can be performed interactively in the text editor via the menu option Include -> Symbols -> Text. This method is available for all text symbols belonging to a text module as well as those of the associated layout set.


Values defined in this way are lost when the transaction is left. If the text module is to be printed again then the symbol values must all be entered again. The purpose of the DEFINE command is to provide a means of making this value assignment a permanent part of the text, so that the values are available again when the text module is called again. This command can also be used to re-assign a new value to a text symbol part way through the text.


Syntax:
/: DEFINE &symbol_name& = 'value'

/: DEFINE &subject& = 'Your letter of 7/3/95'
The value assigned can have a maximal length of 60 characters. It may itself contain other symbols. A symbol contained within the value assigned to another symbol is not replaced with its own value at the point at which the DEFINE command is executed. Rather, this replacement is made when the symbol defined in the DEFINE command is called in the text.



/: DEFINE &symbol1& = 'mail'
/: DEFINE &symbol2& = 'SAP&symbol1&'
/: DEFINE &symbol1& = 'script'
&symbol2& -> SAPscript


If, however, the DEFINE command is written using the ':=' character rather than the '=' character, then any symbol contained within the value being assigned will be replaced immediately with its current value. The assignment to the target symbol will only be made after all symbols in the value string have been replaced with their values. The total length of the value string may not exceed 80 characters. The target symbol must be a text symbol, as before.



/: DEFINE &symbol1& = 'mail'
/: DEFINE &symbol2& := 'SAP&symbol1&'
/: DEFINE &symbol1& = 'script'
&symbol2& -> SAPmail


Formatting Date Fields: SET DATE MASK

The formatting for date fields can be defined with the SET DATE MASK control command. Executing this command causes all subsequent date fields to be output using the specified format.


Syntax:
/: SET DATE MASK = 'date_mask'
The following codes can be used in the date mask:



• DD: day (two digits)
• DDD: day name - abbreviated
• DDDD: day name - written out in full
• MM: month (two digits)
• MMM: month name - abbreviated
• MMMM: month name - written out in full
• YY: year (two digits)
• YYYY: year (four digits)
• LD: day (formatted as for the L option)
• LM: month (formatted as for the L option)
• LY: year (formatted as for the L option)



All other characters found in a date mask are interpreted as simple text and are copied straight into the output.




Assuming the current system date is March 1st, 1994.
/: SET DATE MASK = 'Foster City, MM/DD/YY'
&DATE& -> Foster City, 03/01/94
/: SET DATE MASK = 'MMMM DD, YYYY'
&DATE& -> March 01, 1994
The date mask may be reset to the default setting by using an empty string:
/: SET DATE MASK = ' '




The abbreviated and full forms of the names of the days and months are stored in the language dependent TTDTG table under the following keys:



• %%SAPSCRIPT_DDD_dd: abbreviated day name
• %%SAPSCRIPT_DDDD_dd: full form of day name
• %%SAPSCRIPT_MMM_mm: abbreviated month name
• %%SAPSCRIPT_MMMM_mm: full form of month name

dd: day number 01 = Monday, ..., 07 = Sunday
mm: month number 01 = January, ..., 12 = December

Formatting Time Fields: SET TIME MASK




You can use the SET TIME MASK control command to format time fields as you require. Executing this command causes all subsequent time fields to be output using the specified format.



Syntax:
/: SET TIME MASK = 'time_mask'
The following codes can be used in the time mask:

• HH hours (two digits)
• MM minutes (two digits)
• SS seconds (two digits)


All other characters found in a time mask are interpreted as simple text and are copied straight into the output.

Assuming the current time is 10:08:12,
/: SET TIME MASK = 'HH:MM'
&TIME& -> 10:08
/: SET TIME MASK = 'HH hours MM minutes'
&TIME& -> 10 hours 08 minutes
The time mask may be reset to the default setting by using an empty string:
/: SET TIME MASK = ' '


Country-Dependent Formatting: SET COUNTRY

The formatting for certain field types depends on the country settings. These field types include, for example, date fields and number fields that include either a decimal point or the 'thousands' separator character. The formatting options defined in the user master record are usually the ones used here. The SET COUNTRY control command can be used to select a formatting option other than that specified in the user master record. The country-dependent formatting options are stored in the T005X table.


Syntax:
/: SET COUNTRY country_key
The country key can be specified either as a literal value enclosed in quotes or as a symbol.

/: SET COUNTRY 'CAN'
/: SET COUNTRY &country_key&
A blank country name can be used to revert to the setting found in the user master record:
/: SET COUNTRY ' '
This SAPscript command actually calls the corresponding ABAP command internally. Therefore the effect of the SAPscript command is guaranteed to be identical with that of the ABAP command.



If the formatting turns out not to be as required, then you should check the settings in the T005X table.


Position of the Leading Sign: SET SIGN



The usual convention in business applications is to show the leading sign to the right of the figure to which it applies. However, it is sometimes necessary to show the leading sign to the left of the figure. The SET SIGN control command can be used to specify this globally. Executing this command affects the formatting of all subsequent program symbols that possess a leading sign.


Syntax:
/: SET SIGN LEFT
The leading sign is output to the left of the number.
/: SET SIGN RIGHT
The leading sign is output to the right of the number.

Initializing Numbered Paragraphs: RESET

The RESET control command is used to reset the numbering of an outline paragraph to its initial value. If the RESET command is not used, then the numbering of all outline paragraphs in a text will be continuous. If the name of an outline paragraph is specified in the RESET command, then its paragraph numbering and that of subordinate paragraphs will be reinitialized.


Syntax:
/: RESET paragraph_format
The paragraph format specifies the outline paragraph to be reset.



Assume that the paragraph N1 is defined in the style you are using. This kind of paragraph is intended for enumerated lists and causes a sequential number to be output.


* Proceed as follows if you want to work with the SAP R/3
system:
N1 Ensure that you have a PC
N1 Switch the PC on
N1 Click on the SAP icon using the mouse.
* You will then enter the SAP logon screen. In order to log
on here, you must carry out the following actions:
/: RESET N1
N1 Enter your user name
N1 Enter your password
N1 Select the application you want to use



This text specification would be output as follows:
Proceed as follows if you want to work with the SAP R/3
system:
1. Ensure that you have a PC
2. Switch the PC on
3. Click on the SAP icon using the mouse.
You will then enter the SAP logon screen. In order to log on here, you must carry out the following actions:
1. Enter your user name
2. Enter your password
3. Select the application you want to use


If there were no RESET command between the two sections, then the two lists would be numbered in a single sequence:

Proceed as follows if you want to work with the SAP R/3
system:


1. Ensure that you have a PC
2. Switch the PC on
3. Click on the SAP icon using the mouse.
You will then enter the SAP logon screen. In order to log on here, you must carry out the following actions:
4. Enter your user name
5. Enter your password
6. Select the application you want to use



Initializing Numbered Paragraphs: RESET

The RESET control command is used to reset the numbering of an outline paragraph to its initial value. If the RESET command is not used, then the numbering of all outline paragraphs in a text will be continuous. If the name of an outline paragraph is specified in the RESET command, then its paragraph numbering and that of subordinate paragraphs will be reinitialized.


Syntax:
/: RESET paragraph_format
The paragraph format specifies the outline paragraph to be reset.

Assume that the paragraph N1 is defined in the style you are using. This kind of paragraph is intended for enumerated lists and causes a sequential number to be output.


* Proceed as follows if you want to work with the SAP R/3
system:
N1 Ensure that you have a PC
N1 Switch the PC on
N1 Click on the SAP icon using the mouse.


* You will then enter the SAP logon screen. In order to log
on here, you must carry out the following actions:
/: RESET N1
N1 Enter your user name
N1 Enter your password
N1 Select the application you want to use
This text specification would be output as follows:


Proceed as follows if you want to work with the SAP R/3
system:


1. Ensure that you have a PC
2. Switch the PC on
3. Click on the SAP icon using the mouse.
You will then enter the SAP logon screen. In order to log on here, you must carry out the following actions:
1. Enter your user name
2. Enter your password
3. Select the application you want to use


If there were no RESET command between the two sections, then the two lists would be numbered in a single sequence:

Proceed as follows if you want to work with the SAP R/3
system:


1. Ensure that you have a PC
2. Switch the PC on
3. Click on the SAP icon using the mouse.


You will then enter the SAP logon screen. In order to log on here, you must carry out the following actions:
4. Enter your user name
5. Enter your password
6. Select the application you want to use

Including Other Texts: INCLUDE


You can use the INCLUDE control command to include the contents of another text into the current text. The text to be included continues to be treated as a separate text and is copied over only at the point at which the output is formatted.


Thus the use of the INCLUDE command always ensures that the most current version of a text is included into the output, since the text is not read and inserted until the output is formatted.
Syntax:
/: INCLUDE name [OBJECT o] [ID i] [LANGUAGE l] [PARAGRAPH p]
[NEW-PARAGRAPH np]


The name of the text to be inserted must be specified and can be up to 70 characters long. If the name of the text contains spaces, then it must be enclosed in quotes as a literal value. The name may alternatively be specified via a symbol. All remaining parameters in the INCLUDE command are optional. If an optional parameter is not specified, then SAPscript uses default values as applicable for the calling environment.



/: INCLUDE MYTEXT
The text MYTEXT is included in the language of the calling text.
/: INCLUDE MYTEXT LANGUAGE 'E' PARAGRAPH 'A1'
The text with the name MYTEXT and the language E is included, regardless of the language of the calling text. The paragraph format A1 will be used as the standard paragraph type for this call.

Optional parameters:

• LANGUAGE

If this parameter is not specified, then the language of the calling text or the layout set language are used for the text to be included. If the language is specified, then the text will be fetched in this language, regardless of the language of the calling text.

• PARAGRAPH

The text to be included is formatted using the style allocated. The PARAGRAPH parameter can be used to redefine the standard paragraph for this style for the current call. All *-paragraphs in the included text will then be formatted using the paragraph specified here.

• NEW-PARAGRAPH

The first line of the text to be included will be given this format indicator, as long as it is not a comment or command line. If the optional PARAGRAPH parameter (see above) is not specified, then all *-paragraphs of the included text will also be formatted using the paragraph np specified in the NEW-PARAGRAPH command.

• OBJECT

In order to completely specify a text, information about the text object is also required. There are a number of restrictions and other rules that depend on the object type of the calling text:

- Any kind of text can be included in a layout set. If no object is specified, then TEXT will be used (standard texts).


- In the case of a document text (DOKU object), you can include only document texts. This object type will also be assumed if no object is specified in this environment.
- Only hypertexts and document texts can be included in a hypertext (DSYS object). If the OBJECT parameter is missing, then DSYS is used as the default value.


- In the other kinds of text you can include only standard texts (TEXT object), document texts or hypertexts. If there is no specification, then the default object is TEXT.

• ID

The text-ID is a part of the text key which permits further text objects within a given object. If no ID is specified, then the default include ID is used from the TTXID table for the calling text. If there is no entry in this table, then the text-ID of the calling text is used.

The following consistency check is applied both to the ID and the object:

• All text-IDs are allowed in a layout set.
• In document texts only document texts may be included which have text-IDs TX (general texts) or UO (authorization objects) and also other document texts which have the same text-ID as the calling document text.


• In DSYS texts all DSYS texts can be included, whatever ID they have. Document texts to be included must have one of the IDs TX and UO.
• Standard texts with any allowable text-ID, DSYS texts with all IDs and document texts with the IDs TX and UO can be included into the other texts.

The INCLUDE command returns a status code in the SAPSCRIPT-SUBRC symbol:

• 0: the text include was successful.
• 1: the command could not be executed because it contained syntax errors.
• 2: the rules governing the text to be included were not followed (see above).

This value cannot occur if the command is used in a SAPscript layout set.

• 4: the specified text could not be found.


Changing the Style: STYLE

The STYLE control command allows you to change the style within a text. The new style is in force until another STYLE command is issued. If * is specified as the name of style, then the system reverts to the original style.


Syntax:
/: STYLE style
/: STYLE *


The STYLE command is automatically set in the text editor if another text module is inserted and immediately expanded using the menu option Include ® Text. The same thing happens if the contents of texts that have been included using INCLUDE are copied into the text via Edit ® Selected area ® Expand INCLUDE.

Formatting Addresses: ADDRESS

The ADDRESS - ENDADDRESS control command formats an address according to the postal convention of the recipient country defined in the COUNTRY parameter. The reference fields are described in the structures ADRS1, ADRS2, or ADRS3, depending upon the type of address. Either direct values or symbols may be assigned to the parameters.


Syntax:
/: ADDRESS [DELIVERY] [TYPE t] [PARAGRAPH a] [PRIORITY p] [LINES l]
/: TITLE title
/: NAME name1[,name2[,name3[,name4]]]
/: PERSON name of natural person [TITLE form of address]
/: DEPARTMENT department
/: STREET street name
/: LOCATION additional location information
/: POBOX po box [CODE post code / zip code] [CITY city]
/: POSTCODE post code / zip_code
/: CITY city1[,city2]
/: REGION county / state
/: COUNTRY recipient country [LANGUAGE language code]
/: FROMCOUNTRY sender country
/: ADDRESSNUMBER address number
/: ENDADDRESS



The parameter values contain both formatting and address information. The address data are formatted for output according to the data in the following parameters:



• TYPE
• FROMCOUNTRY
• COUNTRY
• LANGUAGE
• PRIORITY
• DELIVERY; and
• LINES



For more information, please also see the on-line documentation for the SAP function module ADDRESS_INTO_PRINTFORM (transaction SE37).
If DELIVERY is not specified and if a POBOX is specified, then it is used in an address instead of a STREET.

Parameters

• DELIVERY

Means that the address should be formatted as a complete delivery address, i.e. using the street name and number rather than the P. O. Box.

• TYPE

Specifies the type of address. The following types are possible:

- 1 normal address (ADRS1). This is the address of a company or organization. It corresponds to the address structure that is expected in most SAP applications.
- 2 private or personal address (ADRS2). This is the address of a natural person, a private or home address.


- 3 company address (ADRS3) with contact person. This is the address of a colleague or contact within a company or organization. The company name should be specified in the TITLE and NAME fields; the ATTN: contact person should be named in PERSON and TITLE.

Should you enter another address type or leave the field blank, then type 1 is used for formatting.



• PARAGRAPH

Specifies the paragraph format to be used for outputting the address. If this parameter is not given, the address will be output using the default paragraph format.

• PRIORITY

Specifies which of the address lines may be omitted should this be necessary. Any combination of the following codes may be specified. The order in which you list the codes determines the order in which address lines are left out.
The codes are as follows:

- A title
- P mandatory empty line
- 4 name4
- 3 name3
- R region
- T neighborhood, administrative section of a city (CITY2)
- D department
- L country name
- C post code or zip code
- 2 name2
- B P.O. Box (Japan only)
- S street name and number or P.O. Box, depending upon DELIVERY parameter
- N name and form of address of natural person (PERSON and TITLE)
- I Location information in LOCATION
- O city

• LINES

This specifies how many lines may be used for formatting the address. If there are too few lines available to allow all the address data to be formatted, then the data specified in the PRIORITY parameter are omitted. If there is no LINES parameter and if this command is in a layout set window of a type other than MAIN, then the number of lines available for formatting the address are automatically calculated based on the current output position and the size of the window.

• TITLE

Title or form of address. Used only with addresses of types 1 and 3.

• NAME

Up to four names may be given, separated by commas. Used only with addresses of types 1 and 3.

• PERSON

Name of the addressee. Used only for addresses of type 2 (private or personal address) or type 3 (company contact address). In type 3 addresses, use PERSON for the name of your contact person: 'Attn: Mr. Jeffries'. The name fields should be used for the company address.

• TITLE (with PERSON)

Title of the addressee. Used only for addresses of type 2 or type 3 (private or personal address).

• DEPARTMENT

Department of the addressee. Used only for addresses of type 3 (company address).

• STREET

Street name, including the street number(s).

• LOCATION

Additional location information, such as the building, "Upstairs Apartment" and so on. Appears on its own line in the address.

• POBOX

P. O. Box.

• CODE

The post code / zip code of the P. O. Box if this is different than the post code / zip code of the recipient.

• CITY

The city in which the destination P.O. Box is located if this is different than the city of the recipient.

• POSTCODE

Post code / zip code of the recipient.

• CITY

Addressee's city. city1 is expected to be the city; city2 is the neighborhood or administrative section, if required.

• REGION

This allows an administrative region, county, province, or state etc. to be specified.

• COUNTRY

Specifies the recipient country, i.e. the country according to whose postal conventions the address is to be formatted.

• LANGUAGE

Language code of the language of the recipient country, if different than that of the recipient COUNTRY. Example: addresses in Switzerland. Standard SAP language codes are used; you can display these in the initial SAPscript text processing screen or in table T002.

• FROMCOUNTRY

Specifies the language to be used for formatting the name of the recipient country. For most European countries, the recipient country is specified by placing the international car registration letters in front of the post code and separating them from the post code with a hyphen.

• ADDRESSNUMBER

An address number for use in special cases, such as addressing in Japan. The number is used to index a central address file, from which the desired address is read. You can find more information on this facility in the documentation for the function module ADDRESS_INTO_PRINTFORM (transaction SE37).



/: ADDRESS
/: TITLE 'Firma'
/: NAME 'Schneider & Co', 'Finanzberatung'
/: STREET 'Kapitalgasse 33'
/: POBOX '12345' CODE '68499'
/: POSTCODE '68309'
/: CITY 'Mannheim'
/: COUNTRY 'DE'
/: FROMCOUNTRY 'DE'
/: ENDADDRESS
produces the following output address:
Firma
Schneider & Co
Finanzberatung
Postfach 12345



68499 Mannheim
If the DELIVERY parameter is specified on the ADDRESS command, then the street name and number will appear in the address in place of the P. O. Box number.
Firma
Schneider & Co
Finanzberatung
Kapitalgasse 33

68309 Mannheim

SAPscript makes an internal call to the ADDRESS_INTO_PRINTFORM function module for formatting the address. If the result is not as expected, you should check the settings for this function module (see the function module documentation (transaction SE37)).

Setting a Header Text in the Main Window: TOP

You can use the TOP .. ENDTOP control command to specify lines of text which are always to be output at the top of the main window. These text lines are also known as header texts. An example of the use of header texts in the case of a very long table covering several pages of output would be to ensure that the table heading information were repeated at the start of each new page of output.





Syntax:
/: TOP
:
:
/: ENDTOP
The lines of text enclosed between the two control commands will be output from now on at the start of the main window.
An existing header text can be disabled by using the TOP .. ENDTOP command pair without enclosing any text lines between the two command lines:
/: TOP
/: ENDTOP
Subsequent pages will contain no header text.



• If the main window already contains some output then a newly specified header text takes effect on the next page only.
• The same applies to the deletion of a header text. If a header text has already been output on the current page then it cannot be retracted.


• Header texts should not be employed in texts that are printed from applications programs, e.g. reminder texts, order texts, etc. These applications programs can also work with header texts via the layout set interface, which may lead to unexpected results.

Setting a Footer Text in the Main Window: BOTTOM

Footer texts may also be specified for the main window in a similar way to header texts. Footer texts are always output at the bottom of the window.


Syntax:
/: BOTTOM
:
:
/: ENDBOTTOM
The lines of text enclosed between the two control commands will be output from now on at the bottom of the main window.
An existing footer text can be disabled by using the BOTTOM .. ENDBOTTOM command pair without enclosing any text lines between the two command lines:
/: BOTTOM
/: ENDBOTTOM


This and subsequent pages will contain no footer text.



• Assuming there is still sufficient space in the main window, a newly specified footer text will also be output on the current page.
• Footer texts should not be employed in texts that are printed from applications programs, e.g. reminder texts, order texts, etc. These applications programs can also work with footer texts via the layout set interface, which may lead to unexpected results.

Conditional Text: IF

You can use the IF control command to specify that text lines should be output only when certain conditions are met. If the logical expression contained within the IF command evaluates to be true, then the text lines enclosed by the IF ... ENDIF command pair will be output. Otherwise they are ignored.


Syntax:
/: IF condition
:
:
/: ENDIF
The logical expression can use the following the comparison operators:

• = EQ equal to
• <> GT greater than
• <= LE less than or equal to • >= GE greater than or equal to
• <> NE not equal to

The following logical connective operators can be used to combine conditions:

• NOT
• AND
• OR



Evaluation of both the individual logical expressions and of the combinations of expressions is performed strictly from left to right. There are no precedence rules. Bracketed expressions are not supported.


The comparison is always performed on literal values, i.e. the symbols are formatted as character strings before being compared rather than using the internal form. This is particularly significant in the case of program symbols, because the formatting of these may depend on various parameters. For example, the formatted form of a currency field employs a variable number of decimal places and a variable 'decimal point' symbol (e.g. a period or a comma) depending on the applicable currency key.


The IF command may be extended with the ELSE command to allow text lines to be specified which are to be output in the case that the condition evaluates to be false. The text lines enclosed by the IF and ELSE commands are formatted if the condition is true; otherwise the text lines enclosed by the ELSE and ENDIF commands are formatted.


Syntax:
/: IF condition
:
/: ELSE
:
/: ENDIF
The ELSEIF command allows multiple cases to be specified.
Syntax:
/: IF condition
:
/: ELSEIF condition
:
/: ELSE
:
/: ENDIF


You can use arbitrarily many ELSEIF commands within one compound IF .. ENDIF control command. The use of an ELSE command is then optional.
Notes:

• A condition may not occupy several lines. Both the IF or ELSEIF command and the attached condition must be completely contained within a single line.
• IF commands may be nested.
• An IF command must be terminated with an ENDIF command. If this is forgotten, then there will be no more output following the IF command if the condition evaluates to be false.
• If a syntax error occurs in the interpretation of this command, then the command will not be executed. This may have an unexpected effect on the subsequent text output. For example if the IF statement is incorrect, then all following ELSEIF and ELSE commands will be ignored, since the opening IF command is 'missing'. This will cause all the text lines attached to the ELSEIF and ELSE commands to be output.



The CASE command

The CASE command covers a special case of the multiple case IF command. Rather than allowing an arbitrary condition to be tested in each of the individual cases (as in the general multiple case IF command), the CASE command allows a given symbol to be tested against specific values until a matching value is found.


Syntax:
/: CASE symbol
/: WHEN value1
:
/: WHEN value2
:
/: WHEN valuen
:
/: WHEN OTHERS.
:
/: ENDCASE


The symbol in the CASE line is formatted. If its value is to be found in one of the WHEN lines, then the text lines following this WHEN line are output. If no matching value is found then the text lines enclosed by the WHEN OTHERS line and the ENDCASE command are output. The WHEN OTHERS section is optional.


As in the case of the IF command, the comparison is always performed on literal values.

• A CASE command must be terminated by an ENDCASE command.
• The WHEN OTHERS section is optional.


Calling ABAP/4 Subroutines: PERFORM

You can use the PERFORM command to call an ABAP/4 subroutine (form) from any program, subject to the normal ABAP/4 runtime authorization checking. You can use such calls to subroutines for such purposes as carrying out calculations, obtaining data from the database that is needed at display or print time, format data, and so on.


PERFORM commands, like all control commands, are executed when a document is formatted for display or printing. Communication between a subroutine that you call and the document is by way of symbols whose values are set in the subroutine.


Syntax:
/: PERFORM IN PROGRAM
/: USING &INVAR1&
/: USING &INVAR2&
......
/: CHANGING &OUTVAR1&
/: CHANGING &OUTVAR2&
......
/: ENDPERFORM


INVAR1 and INVAR2 are variable symbols and may be of any of the four SAPscript symbol types.

OUTVAR1 and OUTVAR2 are local text symbols and must therefore be character strings.

The form routine that you call with PERFORM may not contain any calls to the function modules of the SAPscript composer API (OPEN_FORM, WRITE_FORM, and so on).



Inserting Print Controls: PRINT-CONTROL

You can use this command to call certain printer functions from a SAPscript text. Although you cannot enter control characters for the printer directly in your text, you can define a print control via the spooler maintenance transaction SPAD that contains the printer commands you want. You can now call a print control using the PRINT-CONTROL SAPscript command.


Syntax:
/: PRINT-CONTROL name
Specify the name of the print control either with or without inverted commas.


• The contents of the print control called are transparent to SAPscript. SAPscript cannot check whether the printer commands contained in the control are correct. Therefore, if you experience problems when printing a text containing these commands, you should proceed by first trying to print the text without the print controls. Then, reintroduce the PRINT-CONTROL commands one by one until the command causing the problem is identified.


• You should ensure that the printer control sequences you define leave the printer afterwards in a well-defined state. SAPscript assumes that after completing each text output certain settings (e.g. font, current page) are still valid for subsequent printing. If your printer commands change these settings without resetting them again afterwards, the results may be unpredictable.

After executing a PRINT-CONTROL command SAPscript inserts a space character at the start of the next text line. If you do not want this, then you should give this text line the '=' paragraph format.


Boxes, Lines, Shading: BOX, POSITION, SIZE

The BOX, POSITION and SIZE commands for drawing boxes, lines and shadowing can be used for specifying that within a layout set particular windows or passages of text within a window are to be output in a frame or with shadowing.


The SAP printer drivers that are based on page-oriented printers (the HP LaserJet driver HPL2, the Postscript driver POST, the Kyocera Prescribe driver PRES) employ these commands when outputting. Line printers and page-oriented printers not supported in the standard ignore these commands. The resulting printer output may be viewed in the SAPscript print previewer.


Syntax:

1. /: BOX [XPOS] [YPOS] [WIDTH] [HEIGHT] [FRAME] [INTENSITY]
2. /: POSITION [XORIGIN] [YORIGIN] [WINDOW] [PAGE]
3. /: SIZE [WIDTH] [HEIGHT] [WINDOW] [PAGE]

BOX Command

Syntax


/: BOX [XPOS] [YPOS] [WIDTH] [HEIGHT] [FRAME] [INTENSITY]
Effect: draws a box of the specified size at the specified position.
Parameters: For each of XPOS, YPOS, WIDTH, HEIGHT and FRAME both a measurement and a unit of measurement must be specified. The INTENSITY parameter should be specified as a percentage between 0 and 100.

1. XPOS, YPOS: Upper left corner of the box, relative to the values of the POSITION command.

Default: Values specified in the POSITION command.
The following calculation is performed internally to determine the absolute output position of a box on the page:
X(abs) = XORIGIN + XPOS
Y(abs) = YORIGIN + YPOS

2. WIDTH: Width of the box. Default: WIDTH value of the SIZE command.
3. HEIGHT: Height of the box. Default: HEIGHT value of the SIZE command.
4. FRAME: Thickness of frame.

Default: 0 (no frame).

5. INTENSITY: Grayscale of box contents as % .

Default: 100 (full black)

Measurements: Decimal numbers must be specified as literal values (like ABAP numeric constants) by being enclosed in inverted commas. The period should be used as the decimal point character. See also the examples listed below.
Units of measurement: The following units of measurement may be used:

• TW (twip)
• PT (point)
• IN (inch)
• MM (millimeter)
• CM (centimeter)
• LN (line)
• CH (character).

The following conversion factors apply:

• 1 TW = 1/20 PT
• 1 PT = 1/72 IN
• 1 IN = 2.54 CM
• 1 CM = 10 MM
• 1 CH = height of a character relative to the CPI specification in the layout set header
• 1 LN = height of a line relative to the LPI specification in the layout set header



/: BOX FRAME 10 TW
Draws a frame around the current window with a frame thickness of 10 TW (= 0.5 PT).
/: BOX INTENSITY 10
Fills the window background with shadowing having a gray scale of 10 %.
/: BOX HEIGHT 0 TW FRAME 10 TW
Draws a horizontal line across the complete top edge of the window.
/: BOX WIDTH 0 TW FRAME 10 TW
Draws a vertical line along the complete height of the left hand edge of the window.
/: BOX WIDTH '17.5' CM HEIGHT 1 CM FRAME 10 TW INTENSITY 15
/: BOX WIDTH '17.5' CM HEIGHT '13.5' CM FRAME 10 TW
/: BOX XPOS '10.0' CM WIDTH 0 TW HEIGHT '13.5' CM FRAME 10 TW
/: BOX XPOS '13.5' CM WIDTH 0 TW HEIGHT '13.5' CM FRAME 10 TW
Draws two rectangles and two lines to construct a table of three columns with a highlighted heading section.

POSITION Command

Syntax
/: POSITION [XORIGIN] [YORIGIN] [WINDOW] [PAGE]
Effect: Sets the origin for the coordinate system used by the XPOS and YPOS parameters of the BOX command. When a window is first started the POSITION value is set to refer to the upper left corner of the window (default setting).


Parameters: If a parameter value does not have a leading sign, then its value is interpreted as an absolute value, in other words as a value which specifies an offset from the upper left corner of the output page. If a parameter value is specified with a leading sign, then the new value of the parameter is calculated relative to the old value. If one of the parameter specifications is missing, then no change is made to this parameter.

1. XORIGIN, YORIGIN: Origin of the coordinate system.
2. WINDOW: Sets the values for the left and upper edges to be the same of those of the current window (default setting).
3. PAGE: Sets the values for the left and upper edges to be the same of those of the current output page (XORIGIN = 0 cm, YORIGIN = 0 cm).

/: POSITION WINDOW
Sets the origin for the coordinate system to the upper left corner of the window.
/: POSITION XORIGIN 2 CM YORIGIN '2.5 CM'
Sets the origin for the coordinate system to a point 2 cm from the left edge and 2.5 cm from the upper edge of the output page.
/: POSITION XORIGIN '-1.5' CM YORIGIN -1 CM
Shifts the origin for the coordinates 1.5 cm to the left and 1 cm up.

SIZE Command

Syntax
/: SIZE [WIDTH] [HEIGHT] [WINDOW] [PAGE]
Effect: Sets the values of the WIDTH and HEIGHT parameters used in the BOX command. When a window is first started the SIZE value is set to the same values as the window itself (default setting).


Parameters: If one of the parameter specifications is missing, then no change is made to the current value of this parameter. If a parameter value does not have a leading sign, then its value is interpreted as an absolute value. If a parameter value is specified with a leading sign, then the new value of the parameter is calculated relative to the old value.

1. WIDTH, HEIGHT: Dimensions of the rectangle or line.
2. WINDOW: Sets the values for the width and height to the values of the current window (default setting).
3. PAGE: Sets the values for the width and height to the values of the current output page.


/: SIZE WINDOW
Sets WIDTH and HEIGHT to the current window dimensions.
/: SIZE WIDTH '3.5' CM HEIGHT '7.6' CM
Sets WIDTH to 3.5 cm and HEIGHT to 7.6 cm.
/: POSITION WINDOW
/: POSITION XORIGIN -20 TW YORIGIN -20 TW
/: SIZE WIDTH +40 TW HEIGHT +40 TW
/: BOX FRAME 10 TW


A frame is added to the current window. The edges of the frame extend beyond the edges of the window itself, so as to avoid obscuring the leading and trailing text characters.


Hexadecimal Data: HEX, ENDHEX

This command can be used to send printer commands in a printer language directly to a printer that supports that language. SAPscript does not interpret the data enclosed by the HEX and ENDHEX command pair, but inserts it unchanged into the output stream.


This technique allows objects with a pixel-oriented format (e.g. graphics) to be printed as part of a SAPscript text. The HEX and ENDHEX command pair enclose the printer commands and data as hexadecimal text, so that the printer formatting routines interpret each successive pair of characters as a single hexadecimal value in the range 0..255.

The characters 0..9 and A..F for representing the values 10..15 are valid hexadecimal characters. The text may also include comment lines (these begin with /* in the format column), which will not be interpreted as hexadecimal data but are simply passed over by the formatting routines.


Syntax:
/: HEX [TYPE printer_language]

The HEX command denotes the start of the hexadecimal data. Subsequent text lines are interpreted as described above. If the TYPE parameter is present, the data will be sent to the printer only if the printer understands the specified printer language. The following printer languages are currently supported: POST (Postscript), PRES (Kyocera Prescribe) and PCL (HP Printer Control Language).


/: HEX [TYPE printer_language] [XPOS x_position] [YPOS y_position]
The output cursor is set to the absolute position indicated by the specified X and Y position parameters before the hexadecimal data is output. If either the X or the Y position is not specified, then 0 will be assumed for this parameter.


/: HEX [TYPE printer_language] [HEIGHT height] [LEFT left_indentation]
The HEIGHT parameter determines the amount of space to be reserved on the page for the output of the hexadecimal data.

Any text following the ENDHEX command will be output below this point. If the LEFT parameter is also specified, then the output of the hexadecimal data will be indented from the left margin by the specified amount.



/: HEX TYPE PCL HEIGHT '7.5' CM LEFT '2.25' CM
/* Creator: report ZQVNTE30 date 19940705 time 125129 user SAPSCRIPT

/= 1B2A7230461B2A743735521B2A7231411B2A62304D1B2A62343057FFFFFFFFFFFF
/= FF1B2A62343057FFFFFFFFFFFFC0007D00DFC0F7D0000000000000000000000017
/: ENDHEX


This data will be printed only by an HP PCL printer (e.g. HP LaserJet). 7.5 cm of space will allocated on the page for the output of the data and the output cursor will be indented 2.25 cm to the right of the layout set window edge.

The RSTXLDMC program may be used to upload correctly formatted pixel data to the R/3 system and to prepare it as a HEX-ENDHEX control command. This can then be saved as normal SAPscript text.

Summing a Program Symbol: SUMMING

The SUMMING command is used for accumulating a total value for a program symbol. The command should be specified just once. Then, each time that the specified program symbol is formatted, its current value is added into the total symbol. Several program symbols may all be added into a single total symbol.


Syntax:
/: SUMMING program_symbol INTO total_symbol
SAPscript cannot create the field for the total dynamically. The symbol used must be defined in a TABLES structure in the calling program.