1 01/24/83  get_entry_point_dcl_
  2 
  3 The get_entry_point_dcl_ subroutine returns attributes needed to
  4 construct a PL/I declare statement for external procedure entry points
  5 and for error_table_ codes and other system-wide external data.  The
  6 program obtains the attributes from data files declaring all unusual
  7 procedure entry points (e.g., ALM segments), and system-wide data
  8 values (e.g., sys_info$max_seg_size), and from the argument descriptors
  9 describing the entry point's parameters that are included with the
 10 entry point itself.
 11 
 12 
 13 Entry points in get_entry_point_dcl_:
 14    (List is generated by the help command)
 15 
 16 
 17 :Entry: get_entry_point_dcl_: 01/19/83  get_entry_point_dcl_
 18 
 19 
 20 Function: returns the declaration for an external value, either from
 21 one of the data files, or by using the parameter argument descriptors
 22 associated with the procedure entry point.  It makes a special case of
 23 error_table_ values by always returning 'fixed bin(35) ext static' for
 24 them.
 25 
 26 
 27 Syntax:
 28 dcl get_entry_point_dcl_ entry (char(*), fixed bin, fixed bin,
 29      char(*) varying, char(32) varying, fixed bin(35));
 30 call get_entry_point_dcl_ (name, dcl_style, line_length, dcl, type,
 31      code);
 32 
 33 
 34 Arguments:
 35 name
 36    is the name of the external entry point or data item whose
 37    declaration must be obtained.  (Input)
 38 dcl_style
 39    is the style of indentation to be performed for the name.  See
 40    "Notes" below for a list of allowed values.  (Input)
 41 line_length
 42    is the maximum length to which lines in return value are allowed to
 43    grow when indentation is performed.  (Input)
 44 dcl
 45    is the declaration that was obtained.  (Output)
 46 
 47 
 48 type
 49    is the type of declaration.  In the current implementation, this is
 50    always a null string.  (Output)
 51 code
 52    is a standard status code describing any failure to obtain the
 53    declaration.  (Output)
 54 
 55 
 56 Notes on styles: Three styles of declaration indentation are supported
 57 by the dcl_style argument described above.
 58 
 59 
 60 Style 0:   (dcl_style = 0)
 61    involves no indentation.  The declaration is returned as a single
 62    line.
 63 
 64 
 65 Style 1:   (dcl_style = 1)
 66    indents the declaration in the format similar to the indent command.
 67    Long declarations are broken into several lines.  For example, a
 68    declare statement for hcs_$initiate_count would appear as:
 69 
 70    dcl  hcs_$initiate_count entry (char(*), char(*), char(*),
 71         fixed bin(24), fixed bin(2), ptr, fixed bin(35));
 72 
 73    when the string "dcl hcs_$initiate_count" is concatenated with the
 74    value returned by get_entry_point_dcl_, and a semicolon (;) is
 75    appended to this value.
 76 
 77 
 78 Style 2:   (dcl_style = 2)
 79    indents the declaration in an alternate format that makes the name
 80    of the entry point stand out from its declaration.  It assumes that
 81    the name of the entry point begins in column 11 (indented one
 82    horizontal tab stop from left margin), and the declaration begins
 83    in column 41.  In style 2, the declare statement for
 84    hcs_$initiate_count would appear as:
 85 
 86    dcl       hcs_$initiate_count           entry (char(*), (char(*), (char(*),
 87                                                 fixed bin(24), fixed bin(2),
 88                                                 ptr, fixed bin(35));
 89 
 90 
 91 Notes: Most command and active function entry points do not declare
 92 arguments in their procedure statements since they accept a variable
 93 number of arguments.  Neither do they use the options(variable)
 94 attribute in their procedure statements.  Therefore, when
 95 get_entry_point_dcl_ encounters a procedure entry point with no
 96 declared arguments and without options(variable), it assumes the
 97 options(variable) attribute required for commands and active functions
 98 and returns:
 99         entry options(variable)
100 
101 
102 It distinguishes between such assumed options(variable) entries and
103 those that explicitly use the options(variable) attribute in their
104 procedure statement by returning "entry" for the assumed case and
105 "entry()" for the explicit case.  Thus, for the display_entry_point_dcl
106 command, which explicitly uses options(variable) in its procedure
107 statement, get_entry_point_dcl_ returns:
108         entry() options(variable)
109 
110 
111 For procedures which use structures as arguments, certain structure
112 declarations are inexactly returned as parameter declarations because
113 the mechanism for encoding argument descriptors does not provide an
114 adequate description of the alignment of a structure.  The descriptor
115 only determines whether the overall structure is packed or not, and
116 does not specify whether or not it was originally declared with the
117 aligned attribute.
118 
119 
120 The following structures generate the same argument descriptors, even
121 though PL/I treats the level 1 structures as having different
122 attributes:
123    dcl 1 s2 structure aligned,
124          2 el1 fixed bin aligned,
125          2 el2 fixed bin aligned;
126 
127    dcl 1 s2 structure,
128          2 el1 fixed bin aligned,
129          2 el2 fixed bin aligned;
130 
131 get_entry_point_dcl_ reproduces the declaration for s2 when either s1
132 or s2 are used as parameters for an entry point.  In order to bypass
133 this problem, declare the subroutine properly in your personal .dcl
134 segment (see "User-Provided Data Files" below), and place this segment
135 in your "declare" search paths.
136 
137 
138 Notes on Search List:
139 The get_entry_point_dcl_ subroutine uses the "declare" search list,
140 which has the synonym "dcl", to find data files describing unusual
141 procedure entry points.  The default search list identifies the data
142 file >sss>pl1.dcl.
143 
144 
145 User-Provided Data Files:
146 Users may provide data files that redeclare standard system entry
147 points (e.g., redeclaring a subroutine as a function), or that declare
148 their own entry points or external data items.  The add_search_paths
149 command can be used to place user-provided data files in the "declare"
150 search list.
151 
152 Declarations have the general form of:
153         virtual_entry declaration
154 For example:
155         ioa_ entry options(variable)
156 Note that the word "dcl" is not included in the data item, nor does the
157 declaration end with a semicolon (;).  External data values are
158 declared in a similar fashion.  For example:
159         iox_$user_output ptr external static