CREATING COMMAND DESCRIPTIONS FOR AXE ERICSSON ///    OPEN INFORMATION DOCUMENT INSTRUCTION  Uppgjord - Prepared ETXCMAR Faktaansvarig - Subject responsibleWilliam Leahy Nr - No2/1013-FCK 114 62 Uen Dokansv/Godk - Doc respons/ApprovedUAB/K/UEC (Henrik Almeida) Kontr - CheckedEEIGCN Datum - Date1996-12-10 RevA File  CREATING COMMAND DESCRIPTIONS FOR AXE Contents 1 Revision Information 2 Application 3 Purpose of this Document Instruction 4 Command Description 4.1 Purpose of a Command Description 4.2 Users of a Command Description 4.3 Identification of a Command Description 4.3.1 Header Information 4.3.2 Naming Conventions 4.4 Contents of a Command Description 5 How to Write a Command Description 5.1 Guidelines and Conventions 5.2 Template and Example Documents 5.3 Section 1, Format 5.3.1 Subsection 1.1, Command 5.3.2 Subsection 1.2, Parameters 5.3.3 Subsection 1.3, Dialogue Parameters 5.4 Section 2, Function 5.4.1 Section 2.n, Format n 5.5 Section 3, Examples 5.6 Section 4, Printouts 5.6.1 Subsection 4.1, Check Printout 5.6.2 Subsection 4.2, Procedure Printouts 5.6.3 Subsection 4.3, Answer Printouts 5.6.4 Subsection 4.4, Result Printouts 5.7 Section 5, Logging 5.8 Section 6, Command Category Group 5.9 Section 7, Command Receiving Block 5.10 Section 8, Glossary 5.11 Section 9, References 5.11.1 Subsection 9.n, Command Descriptions 5.11.2 Subsection 9.n, Printout Descriptions 5.11.3 Subsection 9.n, Application Information 5.11.4 Subsection 9.n, Other References 6 Glossary 7 References 1   Revision Information This is a new document that replaces Document Instruction Command Descriptions (COD) for AXE; 2/1013-FCK 114 19 Uen C. The following changes have been made: The document title was changed.References in running text use italics for titles, and the document numbers were removed. Complete references are available in References, section 6.Headings that refer to sections in the Command Description are written as "Section 1, Format" instead of "1 Format". General changes were made to improve the clarity of the text. The examples were improved. 2   Application This Document Instruction is the only instruction allowed within Ericsson for writing new or modifying existing Command Descriptions for AXE 10. If a deviation is required, a request must be made in accordance with the document Handling of Exemptions, ETX/VQ 170 04-6274, and copied to the Central Maintenance AXE (CMAXE) committee and the Handling AXE (HAXE) committee. This is the only exemption procedure approved by Ericsson Quality Management. This Document Instruction cannot answer all the questions that might arise. If further information is required, contact the MAXE. 3   Purpose of this Document Instruction The purpose of this Document Instruction is to define the structure and contents of a Command Description. 4   Command Description 4.1   Purpose of a Command Description The Command Description describes a command and its parameters, including all possibilities and function variants, and gives explanations and examples on how to use the command. This instruction is valid for all commands implemented Man-Machine Language (MML). 4.2   Users of a Command Description The users of a Command Description include the following: Customer operation, maintenance, and administration personnel, who support and administer the exchangeEricsson design and test personnel, who design and test the softwareEricsson designers and technical writers, who produce additional customer documentation and marketing material The Command Description is delivered to the customer as part of the AXE Operation and Maintenance (O&M) Manual. 4.3   Identification of a Command Description 4.3.1   Header Information The document header must contain information according to the Ericsson Standards document Rules for Writing Documents, which is part of the Office Manual. An interpretation of this document follows (listed according to the labels used in the document header): Document type This is the document type, COMMAND DESCRIPTION, written in full capitalization. Prepared This is the corporate initials of the person who prepared the document. Example: ETXGURE Subject responsible This is the company code and office code, separated by a slash, of the design centre responsible for the content of the document. Example: ETX/TX/DZ No. This is the document number for the Command Description, expressed as n/190 82-xxx nnn nn Uzz where: nPrefix 190 82Decimal class xxx nnn nnProduct number (including ABC class)UzzLanguage code (where zz is the specific language code) Example: 1/190 82-CNT 216 1278 Uen Doc respons/Approved This is the company code and office code of the design office. A dash is placed here until the document is approved. When the document is approved, the company code and office code for the office that has formal responsibility for the document is entered here. The office manager signs the original copy. On the computer stored document, the manager's name is written inside parenthesis to indicate that the document has been approved. Example: ETX/TX/ZZ (G Ericsson) Checked This is the corporate signature of the Local MAXE (LMAXE) who approves the technical content of the document. Example: ETXMALS Date This is the date the document was last revised, expressed as yyyy-mm-dd where: yyyy YearmmMonth dd Day Example: 1997-06-21 Revision This is the revision letter and defines the revision state of the document. Begin with A for a new document. Use capital letters A to Z. Do not use I, O, P, Q, R, U, or W. If the series is not enough when Rev Z has been reached, two letters are used: AA, AB, up to ZZ. If the content of the document is changed, the revision letter must be stepped. Due to customer demand, formal changes are no longer allowed. Example: C is stepped to D, H is stepped to J, and Z is stepped to AA. A preliminary document is indicated by a P before the revision letter, and a numeral, indicating the sequence number, after the revision letter. If a preliminary document must be revised, the sequence number is stepped. Example: PA1 is stepped to PA2. When approved, the P and the number are removed, leaving the new revision letter. Example: PB4 becomes B. 4.3.2   Naming Conventions Command Code The command code must contain five alphanumeric characters and is structured using mnemonics in the English language. The command code consists of the following: Function group, expressed as two alphanumeric characters, for example, BGFunction division within the function group, expressed as two alphanumeric characters, for example, CSTask type, expressed as one alphanumeric character, for example, ENoteFunction division is optional. The command code must be written in capital letters. The complete command code described in the list above will read as follows: BGCSE Title The command title consists of the following: Function group followed by a comma, for example, Business Group Function division within the function group, followed by a comma, for example, Category SetTask type, for example, EndNoteFunction division is optional. Titles must be less than 100 characters long. This is the limitation set in the Product Information Management (PRIM) tool. The complete command title described in the list above will read as follows: Business Group, Category Set, End 4.4   Contents of a Command Description The Command Description has the following contents and levels: 1Format 1.1 Command1.1.nFormat n (optional)1.2Parameters 1.3Dialogue Parameters (optional)2Function 2.n Format n (optional)3 Examples3.nExample n 4 Printouts4.1Check Printout4.2Procedure Printouts 4.3Answer Printouts 4.4Result Printouts 5 Logging6Command Category Group7Command Receiving Block8 Glossary9References 9.nCommand Descriptions (optional)9.nPrintout Descriptions (optional)9.n Application Information (optional) 9.nOther References (optional) 5   How to Write a Command Description This section explains how to write a Command Description. The first part contains the following sections: Guidelines and ConventionsTemplate and Example Documents The second part contains information about the contents of each section and subsection of the Command Description as listed in subsection page 4.4. 5.1   Guidelines and Conventions Style Guidelines Detailed instructions on language and style conventions for O&M documents are found in the Docware Style Manual. Document type names must always be written out in full, that is, do not use an acronym for the document type names: Application InformationCommand DescriptionPrintout Description Text may not be inserted between a level 1 heading and a level 2 heading. For example, no text is allowed between section 1 and 1.1, section 2 and 2.1, and so on. Keep sentences short and language simple. Avoid long strings of nouns. Expand abbreviations and acronyms at their first occurrence in the text. Example: Central Processor (CP) Use an English dictionary. Do not make up new words. Use standards telecommunication terminology and acronyms, that is, approved by the International Telecommunications Union (ITU) or the European Telecommunications Standards Institute (ETSI). General Guidelines Instructions for including each piece of information in the correct tag in the Command Description template for Standard Generalized Markup Language (SGML) are found in User Guide How to Write a Command Description in Text and Graphics. Graphic Guidelines Graphics are not allowed in a Command Description. 5.2   Template and Example Documents When writing a Command Description, use the current version of the Command Description template. The project manager is responsible for providing information about the current versions of Document Instructions, example documents, templates, and tools. The following are the examples of Command Descriptions: Charging Administration, Tariff Class Specification, Initiate (example of more than one format)Frame Handler, Data Link Connection, Print (example of a standard print command)BGC Subscriber Number, Blocking, Initiate (example of a standard initiate command)IO Subsystem Functions, Volume Administration, Load (example of an APZ command)Monitoring, Initiate (example of a command with dialogue parameters) 5.3   Section 1, Format 5.3.1   Subsection 1.1, Command Enter the command format, including all parameters, as described in Design Rule Command Format for AXE. Straight brackets [ ], are used to indicate that the enclosed selections are optional. Curly brackets { }, indicate a choice of parameters. Example: / \ |DEV=dev[,BCH=bch]| MONTI:+ +[,BNB=bnb]; |SNB=snb | \ / 5.3.1.1   Subsection 1.1.n, Format n To reduce the complex use of curly brackets and optional parameters in commands with more than one distinct function, present the different formats separately. Use subsections for each format of the command. Each subsection must have the name Format n where n is a number. The different formats are then to be reflected by corresponding subsections and examples in sections Function and Examples. 5.3.2   Subsection 1.2, Parameters If there are no parameters, insert the following phrase: This command has no parameters. The parameters must be described in such a manner that the technician can easily understand and use them. The terms used in this instruction for describing parameters are defined in table 1. Parameter Term DefinitionsTermDefinitionParameter name This is the parameter name and the parameter value, divided by an equals symbol. This must be included in the parameter list. Example:  DEV=dev   Not all parameters have values, these do not have the equals symbol.  Example:  LCAT   This is the uppercase symbol for the parameter. This must be included in the parameter list.  Example:  DEV Parameter valueThis is the value to the right of the equals symbol.  The parameter value is usually represented in Command Descriptions by the lower case version of the parameter name. This represents a variable value.  Example:  dev  DefinitionThis is a short description of the meaning of the parameter name. This must be included in the parameter list. Example:  Device  Function This is used to further describe the parameter, if the definition is not sufficient.  Example:  This is the device to be blocked. Constant valueThis is a parameter value that is always the same for the command.  Example:  ALL SyntaxThis is a symbolic representation of the format of the value. It is made up of information units, divided by a dash.   Example: Expressed as dety-n where:  Information unitThis is the smallest element of man-machine language. This must be included in the parameter list if the syntax is included.   When the information unit is constant, that is, it is set, the letters in it are written in upper case.  Example: LI    When it is variable, the letters are written in lower case.   Example:  dety  Value range This is the data type and value range from which values and information units can be selected. Example: Identifier 1 - 7 characters  Additional information This is information about the parameter, other than those provided above.  Example:  See the Application Information for the device-owning block.  If necessary, a Command Description may refer to the Application Information of the same, or another product. Parameter names must be the same for all the commands within a command family (commands with the same first four letters in the command code). List the parameters in alphabetical order. A parameter normally consists of a parameter name and a parameter value. Write a short, concise description of the parameter. This description is only a phrase. It is not a complete sentence, and therefore requires no full stop. If the description does not fully explain the function of the parameter, start a paragraph after the description and include information about the function of the parameter. The parameter value consists of one or several arguments. Each argument consists of one or several information units. An information unit can be an identifier, symbolic name, text string, digit string, decimal numeral, hexadecimal numeral, or letter. See Function Specification Man-Machine Language, AX. If there is more than one information unit in the same parameter argument, these must be separated by a dash. Include the value range of each parameter or parameter value in detail. Use only the data types shown in table 2. Data Types and Examples Data typeExampleIdentifier x - y characters or alphanumeric characters Identifier 1 - 7 characters Symbolic name x - y characters Symbolic name 1 - 8 characters Text string x - y characters Text string 1 - 42 characters Digit string x - y digits Digit string 1 - 9 digits Note: Dates and times cannot be numerals, they must be digit strings.    Digit string 00 - 23Numeral (decimal is the default)Numeral 0 - 99 Hexadecimal numeralHexadecimal numeral H'00 - H'0F See also Translation Routines for Command and Printout Parameters . Simple Parameter A simple parameter with its definition is written in the following format: parameterdefinition  function Example: LCAT Load catalogue If this parameter is specified, the magnetic tape file will be loaded into memory. Parameter with Value and Function A parameter value with its definition and a description of the function is written in the following format: parameterdefinition  function  additional information Example: TRG=trg Traffic recording group The traffic recording group records information about calls to and from specified traffic destionation codes. Traffic recording groups are specified by command. Parameter with Constant Values A parameter with definition, function, and constant values is written in the following format: parameter definition  constant valuedefinition  .. ..  ..  constant valuedefinition Example: AREA=area Area to be analysed OPERATING Operating area NON-OPERATING Non-operating area Parameter with Value Range A parameter value with a definition and a value range is written in the following format: parameterdefinition  value range  additional information Example: DIP=dip Digital path Identifier 1 - 7 characters Parameter Value with More than One Information Unit A parameter value with more than one information unit is written in the following format: parameterdefinition function syntax for information unit iu 1definition  function  additional information  iu 2definition  function  additional information  .  .  . iu n definition  function  additional information additional information Example:DEV=dev Device Expressed as dety-n where: dety Device type Identifier 1 - 7 characters n Device number Numeral 1 - 30 For alternative expressions, see the Application Information for block TRAN. PP=pp Physical port This parameter indicates where the loop test is to be performed. Expressed as cm-lm-lu-pp where: cm Communication module Numeral 1 - 95 lm Local modem Numeral 1 - 2 lu Line interface unit Numeral 1 - 8 pp Physical port Numeral 1 - 16 This parameter is application system dependent. "Application system dependent" is used in command parameters to indicate that the enclosed selections are optional in the market. The command, the parameter, and the parameter value can be "application system dependent". Parameter with Additional Information The following is an example of a parameter with additional information: Example: MWI=mwi Message waiting indicator YES Messages waiting NO No messages waiting If the message waiting indication function is not supported by the system, the parameter will not be recognized. 5.3.3   Subsection 1.3, Dialogue Parameters This subsection is only included if dialogue parameters or subcommands are included in the command. NoteThe use of dialogue parameters should be avoided. Since they are not logged, information can be lost. Command with Dialogue Parameters List (in alphabetical order) and describe each dialogue parameter. Example: CON; Initiates trunk offering of the monitoring object. END; Disconnects the monitoring function and ends the dialogue command. NXT; Initiates monitoring on the next channel of the monitoring object. SON; Initiates trunk offering of the monitoring object with speech facility. Command with Subcommands Describe the meaning of each parameter in detail. Indicate that the associated subcommands are described in their own Command Descriptions. Example: 1.1 Command INMCT:SPG=spg,IO=io; (:) subcommand; . . . (:) subcommand; (:) END; 1.2 Parameters IO=io Input/Output (IO) device SPG=spg Support processor group 1.3 Dialogue Parameters subcommand Each subcommand is transferred to the support processor group. The subcommands are described in separate Command Descriptions. END The dialogue is ended. 5.4   Section 2, Function This section describes the function and use of the command. If the command has one format, write the description here. If the command has more than one format, see subsection page 5.4.1. Start the description with the phrase "This command ..." followed by an action verb, such as, initiates, deletes, ends, prints, and so on. Continue the first sentence with a general description of the command. For a command implemented in the SP, continue with the sentence: This command is received in a Support Processor (SP). Continue the description by describing the function of the command in detail. Include default values (excluding parameters) and restart information. If the command leads to a dialogue, describe the dialogue procedure so that it distinguishes between system prompts and what the technician is to input. Conclude the section with one of the following statements: The order remains after system restart.The order does not remain after system restart. The order remains after system restart if the specification procedure has been ended by command <command code>. Orders given by printout and dialogue commands do not remain after system restart. Example: This command prints the routing number information for a business group. Answer printout BUSINESS GROUP ROUTING NUMBER DATA is received. The order does not remain after system restart. 5.4.1   Section 2.n, Format n If the command has more than one format, describe the function of each format in a separate subsection. The heading for each of these subsections is "Format n" with n being the corresponding format number. See the command format. See Charging Administration, Tariff Class Specification, Initiate for an example of a Command Description with more than one format. 5.5   Section 3, Examples Provide as many examples as necessary to illustrate various parameter combinations of the command. At least one example must be included. If a command has more than one format, one example paragraph must be included for each format. Include complex cases of command usage. Use one subsection for each example, "Example n" (where "n" is a number). Each example must be followed by text that indicates the command example result. Include additional relevant information, if applicable. For standard commands, start with the command syntax, followed by one or two paragraphs. For long command dialogues, break up the dialogue and comment throughout. Example: TRMPI:MP=4,TRG=ALL; Measuring program 4 is defined. It contains all defined recording groups. Output is made on the ordering IO device. If the example contains dialogue commands, enclose the system response in parentheses. The system response includes the ready indication colon, and answer printouts received in the dialogue. Example: (<) MONTI:DEV=LIBA-0; (:) (READY FOR CONNECTION) (:) CON; (MONITORING ESTABLISHED) (:) SON; (SPEECH MONITORING ESTABLISHED) (:) NXT; (READY FOR CONNECTION) (:) END; (CONCLUSION OF COMMAND MONTI) (END) NoteFor commands implemented in the SP, do not include path-building commands in the examples.This information should be included in the Operational Instruction. 5.6   Section 4, Printouts Format rules, definitions, and examples of the layout of printouts can be found in Document Instruction Creating Alphanumeric Printout Descriptions for AXE and in Design Rule Printout Format for AXE. 5.6.1   Subsection 4.1, Check Printout A check printout confirms command entry by prompting a renewed execution request. A check printout is only used for dangerous commands, that is, commands that could seriously disturb the operation of the system. Enter "Yes" or "No" depending on whether or not a check printout is issued. 5.6.2   Subsection 4.2, Procedure Printouts A procedure printout is received either immediately after the command is entered or after a check printout has occurred. The use of the PARTLY EXECUTED procedure printout should be avoided because it causes serious problems for remote maintenance. Consult MAXE for guidance if this causes problems. Specify the procedure printouts initiated by the command receiving block. Example: EXECUTED NOT ACCEPTED fault type Fault type: FUNCTION BUSY The function is busy. BUFFER CONGESTION Buffer congestion occurred. FORMAT ERROR The command or a parameter was details incorrectly specified. UNREASONABLE VALUE details The parameter was specified with an unreasonable value. List and explain the fault codes after the procedure printouts in ascending numerical order. Each fault type and code has its own explanation. The explanation must be written in complete sentences, with proper punctuation. All fault codes and their slogans must be explained under the fault type at the end of the Procedures Printout subsection. The fault code slogan must be written in uppercase characters exactly as it appears on the IO device. Fault code slogans of 45 or less characters are recommended as this is the maximum number of characters that can be inserted in the IO buffer in one insert statement, although a maximum of 72 characters are allowed. If a fault code slogan exceeds the page boundary, the fault code slogan should be continued on the next line. Using complete sentences, explain the reason for the fault code and, if possible, describe how to enter the command successfully. Example: FAULT CODE 3 ALL TELECOMMUNICATION SERVICE INDIVIDUALS ARE BUSY All telecommunication service (parameter TES) individuals are busy. The number of telecommunication service individuals in block MBCAN is defined by SAE 737. FAULT CODE 20 ALL MEASURING PROGRAMS ARE BUSY All measuring programs are busy. The number of measuring programs is defined by SAE 022. Details Whenever possible, the system prints the faulty parameter and its block indicated by "details" for the relevant fault type, for example: Command: BLODI:DEV=123; Printed result: NOT ACCEPTED FORMAT ERROR (0)DEV=123 Indicate details for the following: FORMAT ERRORPARTLY EXECUTEDUNREASONABLE VALUEParameters that can be repeated with "&" and "&&" Where fault slogans are not specific enough to identify the faulty parameter For more information about details, see Alphanumerical IO Functions for PLEX Language. Example: FORMAT ERROR The command or a parameter was details incorrectly specified. UNREASONABLE VALUE details The parameter was specified with an unreasonable value. FAULT CODE 6 DEVICE NOT CONNECTED TO SPID details The specified device has no SPID connected. 5.6.3   Subsection 4.3, Answer Printouts If there are no answer printouts, insert the phrase: This command has no answer printouts. List the answer printouts in alphabetical order. Printouts that are received both as result and answer printouts must be listed both in the Answer Printouts subsection and the Result Printouts subsection. Answer printouts that occur either within dialogue or as a result of a command must be described under this heading. For answer printouts within a dialogue, a descriptive text must be given because no Printout Descriptions exist for these printouts. Example: SPEECH MONITORING ESTABLISHED Speech monitoring is established. 5.6.4   Subsection 4.4, Result Printouts If there are no result printouts, insert the phrase: This command has no result printouts. Printouts that are received both as result and answer printouts must be listed both in the Answer Printouts subsection and the Result Printouts subsection. File printouts are also listed in the Result Printout subsection. List the result printouts in alphabetical order. Example: TRADFILE TRAFFIC RECORDING RESULT If printout COMMAND EXECUTED or COMMAND NOT EXECUTED can occur, describe it in detail. Example: COMMAND EXECUTED ANBCI The command was executed. COMMAND NOT EXECUTED ANBCI The command was not executed. fault type Fault type: FAULT CODE 6 NON-OPERATING AREA PROTECTED The non-operating area is in a protected state. A timetable for change may not be specified. 5.7   Section 5, Logging For CP, indicate with "Yes" or "No" whether or not the command is logged. The command log is generated by the system and re-entered after reload. For SP, write "Not relevant". 5.8   Section 6, Command Category Group For the CP, insert the recommended value of the command category group. Example: Recommended value 56 (H'38) The values are divided into function areas in accordance with Design Rule Command Format for AXE. For the SP, insert the following sentence: The authority depends on the category group of the path-building command. The category group within the SP is "x". The x in this statement is one of the following characters: EAXE IO print commandsFAXE IO change commandsGAXE IO dangerous change commands (local authority system) HAXE IO CPT commandsISpareJSpare 5.9   Section 7, Command Receiving Block Write the name of the block that receives the command. Example: BLOC 5.10   Section 8, Glossary If there are no glossary entries in the Command Description, insert the following phrase: This document contains no glossary entries. Expand acronyms and explain terminology used in the Command Description here. Use a definition list and insert acronyms and terms in the left column, and expanded acronyms and explanations in the right column. Parameters are never included in the glossary. 5.11   Section 9, References If a Command Description has no references, insert the following phrase:This document has no references. List all documents referenced in the Command Description. Do not include document numbers. 5.11.1   Subsection 9.n, Command Descriptions Write command codes for the Command Descriptions in full capitalization, followed by the command title (the expanded code) in title capitalization. Example: BUQOE BGC, Attendant Queue, Overload Handler, End 5.11.2   Subsection 9.n, Printout Descriptions Write Printout Description titles using full capitalization. Example: GROUP ADMINISTRATION DATA 5.11.3   Subsection 9.n, Application Information Write only the block names for the Application Information using full capitalization. Example: TRAN 5.11.4   Subsection 9.n, Other References References to documents other than the document covered above are limited. Contact the MAXE for use of other documents. Write other referenced titles using title capitalization. 6   Glossary CMAXECentral MAXECPCentral ProcessorCPTCentral Processor TestETSIEuropean Telecommunications Standards InstituteIOInput/OutputITUInternational Telecommunications UnionHAXEHandling AXELMAXELocal MAXEMAXEMaintenance AXEMMLMan-Machine LanguageO&MOperation and MaintenanceSGMLStandard Generalized Markup LanguageSPSupport Processor 7   References Alphanumerical IO Functions for Plex Language4/155 19-ANZ 218 01 Uen  BGC Subscriber Number, Blocking, Initiate304/1013-FCK 114 62 Uen  Charging Administration, Tariff Class Specification, Initiate 303/1013-FCK 14 62 Uen  Command Format for AXE TM/JE-91:455 Uen  Creating Alphanumeric Printout Descriptions for AXE3/1013-FCK 114 62 Uen  Docware Style Manual2/198 17-FDD 207 08 Uen Frame Handler, Data Link Connection, Print306/1013-FCK 114 62 Uen  Handling of ExemptionsETX/VQ 170 04-6274 How to Write a Command Description in Text and Graphics 2/198 17-CAL 151 0020 Uen  IO Subsystem Functions, Volume Administration, Load302/1013-FCK 114 62 Uen  Man-Machine Language, AX1/155 17-ANZ 218 01 Uen  Monitoring, Initiate305/1013-FCK 114 62 Uen  Office Manual0015-EN/LZB 101 01/1A Uen Printout Format for AXETM/JE-91:456 UEN  Rules for Writing Documents 0034-116 Uen  Translation Routines for Command and Printout ParametersLMI/86B/548 Uen