1 08/22/83  find_include_file_
 2 
 3 
 4 
 5 The primary entry point of the find_include_file_ subroutine searches
 6 for an include file on behalf of a translator.  If the include file is
 7 found, additional information about the segment found is returned in
 8 the parameters.  The "translator" search list is used to locate the
 9 include file.
10 
11 
12 Entry points in find_include_file_:
13    (List is generated by the help command)
14 
15 
16 :Entry:  initiate_count:  05/05/83 find_include_file_$initiate_count
17 
18 
19 Function:  This entry point is the interface presented to translators.
20 A translator calls this entry point to invoke a search for a single
21 include file segment using the "translator" search list.  For more
22 information about search lists, see the search facility commands, and
23 in particular the add_search_paths command in the Commands manual.
24 
25 
26 Syntax:
27 declare find_include_file_$initiate_count entry (char(*), ptr, char(*),
28      fixed bin(24), ptr, fixed bin(35));
29 call find_include_file_$initiate_count (translator, referencing_ptr,
30      file_name, bit_count, seg_ptr, code);
31 
32 
33 Arguments:
34 translator
35    is the name of the translator that is calling this procedure (e.g.,
36    pl1, alm).  (Input)
37 referencing_ptr
38    is a pointer into the segment (normally a pointer to the source
39    line) that caused the invocation of this instance of this procedure.
40    (Input)
41 file_name
42    is the complete entryname of the include file this procedure is to
43    locate (e.g., xxx.incl.pl1).  (Input)
44 bit_count
45    is the bit count as obtained from the storage system of the found
46    include file.  (Output).  If an include file is not found, this
47    parameter is set to 0.
48 
49 
50 seg_ptr
51    is a pointer to the first character of the include file, if found;
52    if not found, this parameter is set to the null pointer value.
53    (Output)
54 code
55    is a standard status code.  (Output).  The code can be:
56    0
57       the requested file was found normally.  All output parameters
58       have been set normally.
59    error_table_$zero_length_seg
60       the requested file was found, but the bit count was zero.  All
61       output parameters have been set normally.
62    error_table_$noentry
63       the requested file was not found in any of the search
64       directories.
65    other storage system error codes
66       the requested file was not found because of some error.
67 
68 
69 Notes:
70 If this procedure finds an include file by a link, the seg_ptr
71 parameter correctly designates the actual location of the include file.
72 It is possible, however, that the name of the actual include file is
73 not the same as the file_name argument passed to this procedure.  It is
74 the responsibility of the translator to determine if the file_name
75 passed to this procedure is also on the include file actually found.
76 It is also the responsibility of the translator to call the
77 hcs_$terminate_noname entry point on the include file when processing
78 is complete.