home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / lpathext.zip / lpathext.ipf < prev    next >
Text File  |  2001-12-11  |  32KB  |  670 lines
  1. :userdoc.
  2. :title.OS&slash.2 LIBPATH Extension Functions
  3. :docprof toc=12.
  4. :h1.Copyright and Notices
  5. :p.IBM and OS&slash.2 are registered trademarks of International Business Machines Corp&per.
  6. :h2.OS&slash.2 LIBPATH Extension Manipulation Functions
  7. :h3.COPYRIGHT AND LICENSING INFORMATION
  8. :p.This suite of subroutines is freeware, distributed as is, without any warranty
  9. of its usefulness for any purpose&per. You may use it freely&per. You may also redistribute it,
  10. provided no charge is levied beyond the price of its distribution medium&per.
  11. :p.However, the author retains all intellectual property rights&per.
  12. .br
  13. .ce Copyright &lpar.C&rpar. David W. Noon, 2001&per.
  14. :h3.OBTAINING TECHNICAL SUPPORT
  15. :p.You can obtain technical support via Internet e&hyphen.mail, Compuserve, or FidoNet Netmail&per.
  16. My addresses are as follows&per.
  17. :font facename='System Monospaced' size=16x12.
  18. :parml compact tsize=15 break=none.
  19. :pt.Internet&colon.
  20. :pd.dwnoon&atsign.os2bbs&per.com
  21. :pt.
  22. :pd.dwnoon&atsign.ntlworld&per.com
  23. :pt.
  24. :pd.dwnoon&atsign.compuserve&per.com
  25. :pt.
  26. :pd.dnoon&atsign.acm&per.org
  27. :pt.Compuserve&colon.
  28. :pd.72172,431
  29. :pt.FidoNet&colon.
  30. :pd.David Noon 2&colon.257&slash.609
  31. :pt.
  32. :pd.David Noon 1&colon.109&slash.347
  33. :eparml.
  34. :font facename=default size=0x0.
  35. :p.The first FidoNet mailbox and the Internet mailboxes I check almost every day&per. The second
  36. FidoNet mailbox and the Compuserve mailbox are checked once or twice a week&per.
  37. :p.Turn&hyphen.around time on problems might not be spectacular, especially if I have other issues
  38. to handle&per. This is freeware and you should expect no more than you pay for&per.
  39. :h1.Preparing these Functions for your Development Environment
  40. :p.The subroutines and functions supplied here are offered as complete source code&per. I have also
  41. included compiled libraries prepared using the EMX&plus.GCC compiler, release 0&per.96d fixpack
  42. &numsign.4&per. Unless you are using this same set&hyphen.up, you will need to compile these
  43. functions with your chosen C&slash.C&plus.&plus. compiler&per. This detail I must leave to you&per.
  44. :p.:hp5.I am assuming that you are familiar with your chosen compiler&apos.s usage of environment
  45. variables to handle its header file and static link library resolution&per.:ehp5.
  46. :p.Once you have suitable libraries built, copy the :hp4.lpathext&per.h:ehp4. file to a directory
  47. that is in your compiler&apos.s INCLUDE directory list&per. For the Watcom compiler,
  48. this will be the OS2&us.INCLUDE directory list&per. For EMX&plus.GCC this will be the
  49. C&us.INCLUDE&us.PATH and CPLUS&us.INCLUDE&us.PATH directory lists&semi. a directory that occurs
  50. in both would be the ideal location&per.
  51. :p.You should also copy the :hp4.lpathext&per.lib:ehp4. file to a directory that is in
  52. your linker&apos.s LIB directory list&per. If you are using EMX&plus.GCC you will need also to copy
  53. :hp4.lpathext&per.a:ehp4. to a directory in the LIBRARY&us.PATH list&per.
  54. :p.You might also care to copy this file, :hp4.lpathext&per.inf:ehp4., to a directory that is in
  55. your BOOKSHELF directory list&per.
  56. :h1.The Two Extensions to LIBPATH for DLL Loading
  57. :p.There are two buffer areas, each 1024 bytes in size, that are provided in each OS&slash.2
  58. address space for directory lists that can be searched to resolve requests to load DLLs&per. One
  59. directory list is searched before the main LIBPATH list is searched&semi. this is the
  60. :hp4.pre&hyphen.system:ehp4. extension&per. The other list is searched after the LIBPATH list
  61. has failed to yield a matching DLL name&semi. this is the :hp4.post&hyphen.system:ehp4.
  62. extension&per.
  63. :p.The purposes of these two extensions are quite straightforward&colon.
  64. :p.The pre&hyphen.system extension is used when you definitely want to override any default
  65. system library with an application&hyphen.specific library&per.
  66. :p.The post&hyphen.system extension is used when you want to proved some :hp1.lowest common
  67. denominator:ehp1. library as a last resort, but expect the user to have installed some
  68. like&hyphen.named library with more specific functionality, typically as some form of
  69. customization, into a LIBPATH directory&per.
  70. :p.You should also be aware that the OS/2 loader performs a lookaside of already&hyphen.loaded
  71. modules for a matching basename before scanning LIBPATH or either of its extensions&per. This means
  72. that if some other application has already loaded a DLL with matching basename, all your attempts
  73. to direct the loading process will be for nought&per. There is only one way to overcome this
  74. problem&colon. :hp5.You must specify a fully qualified path&slash.filename, complete with extension,
  75. to the DosLoadModule&lpar.&rpar. API instead of supplying just the basename&per.:ehp5. While this
  76. is not the idiomatic way to load a library, it is the only way around the basename lookaside
  77. issue&per. If you choose obscure basenames for your dynamic libraries then you will usually
  78. avoid the problem&per. A quick scan through the x&colon.&bsl.OS2&bsl.DLL directory will give
  79. you a hint on what basenames to avoid&semi. a look through x&colon.&bsl.MMOS2&bsl.DLL will provide
  80. you with more basenames to avoid&per.
  81. :p.The purpose of these library routines is to remove the constraint of changing your current
  82. working directory during execution and thereby losing the ability to load DLLs through the
  83. &odq.dot&cdq. entry in the LIBPATH list, as well providing the override and fallback features
  84. of the basic extensions&per.
  85. :note text='Constraint:'.These extensions only take effect after the API or library call has
  86. been made&per. If you use linker fix&hyphen.ups from an import library, the DLL&lpar.s&rpar.
  87. required for those must be present in the LIBPATH &lpar.or the shell&apos.s LIBPATH extensions&rpar.
  88. before the program starts&semi. so these routines will provide you with no help there&per. The
  89. intent of these routines is for those who use DLL technology in the fullest sense of the
  90. adjective &odq.dynamic&cdq., using the DosLoadModule&lpar.&rpar. API or some wrapper function&per.
  91. :h1.The Subroutines
  92. :p.These subroutines are fairly thin wrappers on the :hp4.DosQueryExtLIBPATH&lpar.&rpar.:ehp4. and
  93. :hp4.DosSetExtLIBPATH&lpar.&rpar.:ehp4. API calls&per. You need to be aware that these API calls
  94. were not added to OS&slash.2 until version 2&per.11, so any code that uses these routines will not
  95. run under OS&slash.2 2&per.1 or earlier&per.
  96. :p.You should also be aware that calling these routines will not affect in any way the values
  97. of the surrounding shell&apos.s BEGINLIBPATH and ENDLIBPATH environment variables&per. In fact,
  98. once you start using these routines you should forget all about those environment variables,
  99. as they were always just an ugly kludge&per. &lbrk.That is not to say that this library is not a
  100. kludge too&per. It just isn&apos.t as ugly as the environment variable approach&per.&rbrk.
  101. :h2 res=1 x=0% y=0% height=100% width=30%.set_beginlibpath
  102. :p.This subroutine sets the pre&hyphen.system LIBPATH extension to the directory in which the
  103. executable that started the address space resides&per.
  104. :link reftype=hd res=101 auto.
  105. :sl.
  106. :li.:link reftype=hd res=101.Syntax:elink.
  107. :li.:link reftype=hd res=102.Parameters:elink.
  108. :li.:link reftype=hd res=103.Returned results:elink.
  109. :li.:link reftype=hd res=104.Remarks:elink.
  110. :esl.
  111. :h2 res=101 x=30% y=0% height=100% width=70% viewport hide.set_beginlibpath Syntax
  112. :color fc=blue bc=default.
  113. :font facename='System Monospaced' size=22x16.
  114. :p.unsigned long set_beginlibpath&lpar.void&rpar.&semi.
  115. :font facename=default size=0x0.
  116. :color fc=default bc=default.
  117. .br
  118. :h3.Example of set_beginlibpath
  119. :xmp.
  120. &numsign.include &odq.lpathext&per.h&cdq.
  121. .br
  122. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  123. &lbrc.
  124. :lm margin=4.
  125. &slash.&asterisk. Add program directory to LIBPATH &asterisk.&slash.
  126. if &lpar.set_beginlibpath&lpar.&rpar. &xclm.&eq. 0&rpar.
  127. &lbrc.
  128. :lm margin=7.
  129. fputs&lpar.&odq.Unable to set LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  130. :lm margin=4.
  131. return EXIT&us.FAILURE&semi.
  132. &rbrc.
  133. .br
  134. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  135. :lm margin=1.
  136. .br
  137. &rbrc.
  138. :exmp.
  139. :h2 res=102 x=30% y=0% height=100% width=70% viewport hide.set_beginlibpath Parameters
  140. :p.This function takes no parameters&per.
  141. :h2 res=103 x=30% y=0% height=100% width=70% viewport hide.set_beginlibpath Returned results
  142. :p.This function normally returns zero&per. Any other value indicates an error returned by
  143. the DosSetExtLIBPATH&lpar.&rpar. API, but these should never occur&per.
  144. :h2 res=104 x=30% y=0% height=100% width=70% viewport hide.set_beginlibpath Remarks
  145. :p.If the directory path in which the main executable resides ends with a final node of BIN
  146. &lpar.case&hyphen.insensitive&rpar. then a check is made to see if there exists an otherwise
  147. identical directory path that ends in DLL instead&per. If so, then this DLL directory path
  148. is used instead for the pre&hyphen.system LIBPATH extension&per.
  149. :p.For example, if your program is
  150. :hp8.H&colon.&bsl.Site&us.software&bsl.bin&bsl.Program&us.1&per.exe:ehp8. then the directory path is
  151. :hp8.H&colon.&bsl.Site&us.software&bsl.bin:ehp8.&per. If the directory path
  152. :hp8.H&colon.&bsl.Site&us.software&bsl.dll:ehp8. exists then that is used to set the LIBPATH
  153. extension, otherwise the :hp8.H&colon.&bsl.Site&us.software&bsl.bin:ehp8. path is used&per.
  154. :h2 res=2 x=0% y=0% height=100% width=30%.set_endlibpath
  155. :p.This subroutine sets the post&hyphen.system LIBPATH extension to the directory in which the
  156. executable that started the address space resides&per.
  157. :link reftype=hd res=201 auto.
  158. :sl.
  159. :li.:link reftype=hd res=201.Syntax:elink.
  160. :li.:link reftype=hd res=202.Parameters:elink.
  161. :li.:link reftype=hd res=203.Returned results:elink.
  162. :li.:link reftype=hd res=204.Remarks:elink.
  163. :esl.
  164. :h2 res=201 x=30% y=0% height=100% width=70% viewport hide.set_endlibpath Syntax
  165. :color fc=blue bc=default.
  166. :font facename='System Monospaced' size=22x16.
  167. :p.unsigned long set_endlibpath&lpar.void&rpar.&semi.
  168. :font facename=default size=0x0.
  169. :color fc=default bc=default.
  170. .br
  171. :h3.Example of set_endlibpath
  172. :xmp.
  173. &numsign.include &odq.lpathext&per.h&cdq.
  174. .br
  175. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  176. &lbrc.
  177. :lm margin=4.
  178. &slash.&asterisk. Add program directory to LIBPATH &asterisk.&slash.
  179. if &lpar.set_endlibpath&lpar.&rpar. &xclm.&eq. 0&rpar.
  180. &lbrc.
  181. :lm margin=7.
  182. fputs&lpar.&odq.Unable to set LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  183. :lm margin=4.
  184. return EXIT&us.FAILURE&semi.
  185. &rbrc.
  186. .br
  187. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  188. :lm margin=1.
  189. .br
  190. &rbrc.
  191. :exmp.
  192. :h2 res=202 x=30% y=0% height=100% width=70% viewport hide.set_endlibpath Parameters
  193. :p.This function takes no parameters&per.
  194. :h2 res=203 x=30% y=0% height=100% width=70% viewport hide.set_endlibpath Returned results
  195. :p.This function normally returns zero&per. Any other value indicates an error returned by
  196. the DosSetExtLIBPATH&lpar.&rpar. API, but these should never occur&per.
  197. :h2 res=204 x=30% y=0% height=100% width=70% viewport hide.set_endlibpath Remarks
  198. :p.If the directory path in which the main executable resides ends with a final node of BIN
  199. &lpar.case&hyphen.insensitive&rpar. then a check is made to see if there exists an otherwise
  200. identical directory path that ends in DLL instead&per. If so, then this DLL directory path
  201. is used instead for the post&hyphen.system LIBPATH extension&per.
  202. :p.For example, if your program is
  203. :hp8.H&colon.&bsl.Site&us.software&bsl.bin&bsl.Program&us.1&per.exe:ehp8. then the directory path is
  204. :hp8.H&colon.&bsl.Site&us.software&bsl.bin:ehp8.&per. If the directory path
  205. :hp8.H&colon.&bsl.Site&us.software&bsl.dll:ehp8. exists then that is used to set the LIBPATH
  206. extension, otherwise the :hp8.H&colon.&bsl.Site&us.software&bsl.bin:ehp8. path is used&per.
  207. :h2 res=3 x=0% y=0% height=100% width=30%.query_beginlibpath
  208. :p.This subroutine queries the pre&hyphen.system LIBPATH extension into a buffer supplied by
  209. the caller&per.
  210. :link reftype=hd res=301 auto.
  211. :sl.
  212. :li.:link reftype=hd res=301.Syntax:elink.
  213. :li.:link reftype=hd res=302.Parameters:elink.
  214. :li.:link reftype=hd res=303.Returned results:elink.
  215. :li.:link reftype=hd res=304.Remarks:elink.
  216. :esl.
  217. :h2 res=301 x=30% y=0% height=100% width=70% viewport hide.query_beginlibpath Syntax
  218. :color fc=blue bc=default.
  219. :font facename='System Monospaced' size=22x16.
  220. :p.unsigned long query_beginlibpath&lpar.char &asterisk. buffer&us.area&rpar.&semi.
  221. :font facename=default size=0x0.
  222. :color fc=default bc=default.
  223. .br
  224. :h3.Example of query_beginlibpath
  225. :xmp.
  226. &numsign.include &odq.lpathext&per.h&cdq.
  227. .br
  228. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  229. &lbrc.
  230. :lm margin=4.
  231. char buffer&us.area&lbrk.1024&rbrk.&semi.
  232. .br
  233. &slash.&asterisk. Retrieve current LIBPATH extension &asterisk.&slash.
  234. if &lpar.query_beginlibpath&lpar.buffer&us.area&rpar. &xclm.&eq. 0&rpar.
  235. &lbrc.
  236. :lm margin=7.
  237. fputs&lpar.&odq.Unable to query LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  238. :lm margin=4.
  239. return EXIT&us.FAILURE&semi.
  240. &rbrc.
  241. .br
  242. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  243. puts&lpar.buffer&us.area&rpar.&semi.
  244. &per.
  245. &per.
  246. &per.
  247. :lm margin=1.
  248. .br
  249. &rbrc.
  250. :exmp.
  251. :h2 res=302 x=30% y=0% height=100% width=70% viewport hide.query_beginlibpath Parameters
  252. :p.There is only one parameter for this function&per.
  253. :parml tsize=20 break=all.
  254. :pt.buffer&us.area &lpar.char &lbrk.&rbrk.&rpar.
  255. :pd.Needs to be as large as the current pre&hyphen.system LIBPATH extension string, including
  256. a trailing semi&hyphen.colon and a trailing NUL&per. A length of 1024 will always be safe&per.
  257. :eparml.
  258. :h2 res=303 x=30% y=0% height=100% width=70% viewport hide.query_beginlibpath Returned results
  259. :p.This function normally returns zero&per. Any other value indicates an error returned by
  260. the DosQueryExtLIBPATH&lpar.&rpar. API, but these should never occur&per.
  261. :h2 res=304 x=30% y=0% height=100% width=70% viewport hide.query_beginlibpath Remarks
  262. :p.For some stupid reason, the API always adds a trailing semi&hyphen.colon even though it is
  263. totally redundant&per.
  264. :h2 res=4 x=0% y=0% height=100% width=30%.query_endlibpath
  265. :p.This subroutine queries the post&hyphen.system LIBPATH extension into a buffer supplied by
  266. the caller&per.
  267. :link reftype=hd res=401 auto.
  268. :sl.
  269. :li.:link reftype=hd res=401.Syntax:elink.
  270. :li.:link reftype=hd res=402.Parameters:elink.
  271. :li.:link reftype=hd res=403.Returned results:elink.
  272. :li.:link reftype=hd res=404.Remarks:elink.
  273. :esl.
  274. :h2 res=401 x=30% y=0% height=100% width=70% viewport hide.query_endlibpath Syntax
  275. :color fc=blue bc=default.
  276. :font facename='System Monospaced' size=22x16.
  277. :p.unsigned long query_endlibpath&lpar.char &asterisk. buffer&us.area&rpar.&semi.
  278. :font facename=default size=0x0.
  279. :color fc=default bc=default.
  280. .br
  281. :h3.Example of query_endlibpath
  282. :xmp.
  283. &numsign.include &odq.lpathext&per.h&cdq.
  284. .br
  285. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  286. &lbrc.
  287. :lm margin=4.
  288. char buffer&us.area&lbrk.1024&rbrk.&semi.
  289. .br
  290. &slash.&asterisk. Retrieve current LIBPATH extension &asterisk.&slash.
  291. if &lpar.query_endlibpath&lpar.buffer&us.area&rpar. &xclm.&eq. 0&rpar.
  292. &lbrc.
  293. :lm margin=7.
  294. fputs&lpar.&odq.Unable to query LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  295. :lm margin=4.
  296. return EXIT&us.FAILURE&semi.
  297. &rbrc.
  298. .br
  299. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  300. puts&lpar.buffer&us.area&rpar.&semi.
  301. &per.
  302. &per.
  303. &per.
  304. :lm margin=1.
  305. .br
  306. &rbrc.
  307. :exmp.
  308. :h2 res=402 x=30% y=0% height=100% width=70% viewport hide.query_endlibpath Parameters
  309. :p.There is only one parameter for this function&per.
  310. :parml tsize=20 break=all.
  311. :pt.buffer&us.area &lpar.char &lbrk.&rbrk.&rpar.
  312. :pd.Needs to be as large as the current post&hyphen.system LIBPATH extension string, including
  313. a trailing semi&hyphen.colon and a trailing NUL&per. A length of 1024 will always be safe&per.
  314. :eparml.
  315. :h2 res=403 x=30% y=0% height=100% width=70% viewport hide.query_endlibpath Returned results
  316. :p.This function normally returns zero&per. Any other value indicates an error returned by
  317. the DosQueryExtLIBPATH&lpar.&rpar. API, but these should never occur&per.
  318. :h2 res=404 x=30% y=0% height=100% width=70% viewport hide.query_endlibpath Remarks
  319. :p.For some stupid reason, the API always adds a trailing semi&hyphen.colon even though it is
  320. totally redundant&per.
  321. :h2 res=5 x=0% y=0% height=100% width=30%.clear_beginlibpath
  322. :p.This subroutine sets the pre&hyphen.system LIBPATH extension to an empty string.
  323. :link reftype=hd res=501 auto.
  324. :sl.
  325. :li.:link reftype=hd res=501.Syntax:elink.
  326. :li.:link reftype=hd res=502.Parameters:elink.
  327. :li.:link reftype=hd res=503.Returned results:elink.
  328. :li.:link reftype=hd res=504.Remarks:elink.
  329. :esl.
  330. :h2 res=501 x=30% y=0% height=100% width=70% viewport hide.clear_beginlibpath Syntax
  331. :color fc=blue bc=default.
  332. :font facename='System Monospaced' size=22x16.
  333. :p.unsigned long clear_beginlibpath&lpar.void&rpar.&semi.
  334. :font facename=default size=0x0.
  335. :color fc=default bc=default.
  336. .br
  337. :h3.Example of clear_beginlibpath
  338. :xmp.
  339. &numsign.include &odq.lpathext&per.h&cdq.
  340. .br
  341. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  342. &lbrc.
  343. :lm margin=4.
  344. &slash.&asterisk. Remove LIBPATH extension &asterisk.&slash.
  345. if &lpar.clear_beginlibpath&lpar.&rpar. &xclm.&eq. 0&rpar.
  346. &lbrc.
  347. :lm margin=7.
  348. fputs&lpar.&odq.Unable to clear LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  349. :lm margin=4.
  350. return EXIT&us.FAILURE&semi.
  351. &rbrc.
  352. .br
  353. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  354. :lm margin=1.
  355. .br
  356. &rbrc.
  357. :exmp.
  358. :h2 res=502 x=30% y=0% height=100% width=70% viewport hide.clear_beginlibpath Parameters
  359. :p.This function takes no parameters&per.
  360. :h2 res=503 x=30% y=0% height=100% width=70% viewport hide.clear_beginlibpath Returned results
  361. :p.This function normally returns zero&per. Any other value indicates an error returned by
  362. the DosSetExtLIBPATH&lpar.&rpar. API, but these should never occur&per.
  363. :h2 res=504 x=30% y=0% height=100% width=70% viewport hide.clear_beginlibpath Remarks
  364. :p.This function removes all entries from the pre&hyphen.system LIBPATH directory list&per.
  365. This includes any that might have been put there by the shell from its BEGINLIBPATH environment
  366. variable&per.
  367. :h2 res=6 x=0% y=0% height=100% width=30%.clear_endlibpath
  368. :p.This subroutine sets the post&hyphen.system LIBPATH extension to an empty string.
  369. :link reftype=hd res=601 auto.
  370. :sl.
  371. :li.:link reftype=hd res=601.Syntax:elink.
  372. :li.:link reftype=hd res=602.Parameters:elink.
  373. :li.:link reftype=hd res=603.Returned results:elink.
  374. :li.:link reftype=hd res=604.Remarks:elink.
  375. :esl.
  376. :h2 res=601 x=30% y=0% height=100% width=70% viewport hide.clear_endlibpath Syntax
  377. :color fc=blue bc=default.
  378. :font facename='System Monospaced' size=22x16.
  379. :p.unsigned long clear_endlibpath&lpar.void&rpar.&semi.
  380. :font facename=default size=0x0.
  381. :color fc=default bc=default.
  382. .br
  383. :h3.Example of clear_endlibpath
  384. :xmp.
  385. &numsign.include &odq.lpathext&per.h&cdq.
  386. .br
  387. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  388. &lbrc.
  389. :lm margin=4.
  390. &slash.&asterisk. Remove LIBPATH extension &asterisk.&slash.
  391. if &lpar.clear_endlibpath&lpar.&rpar. &xclm.&eq. 0&rpar.
  392. &lbrc.
  393. :lm margin=7.
  394. fputs&lpar.&odq.Unable to clear LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  395. :lm margin=4.
  396. return EXIT&us.FAILURE&semi.
  397. &rbrc.
  398. .br
  399. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  400. :lm margin=1.
  401. .br
  402. &rbrc.
  403. :exmp.
  404. :h2 res=602 x=30% y=0% height=100% width=70% viewport hide.clear_endlibpath Parameters
  405. :p.This function takes no parameters&per.
  406. :h2 res=603 x=30% y=0% height=100% width=70% viewport hide.clear_endlibpath Returned results
  407. :p.This function normally returns zero&per. Any other value indicates an error returned by
  408. the DosSetExtLIBPATH&lpar.&rpar. API, but these should never occur&per.
  409. :h2 res=604 x=30% y=0% height=100% width=70% viewport hide.clear_endlibpath Remarks
  410. :p.This function removes all entries from the post&hyphen.system LIBPATH directory list&per.
  411. This includes any that might have been put there by the shell from its ENDLIBPATH environment
  412. variable&per.
  413. :h2 res=7 x=0% y=0% height=100% width=30%.append_beginlibpath
  414. :p.This concatenates the supplied list of directories to end of the pre&hyphen.system LIBPATH
  415. extension&per.
  416. :link reftype=hd res=701 auto.
  417. :sl.
  418. :li.:link reftype=hd res=701.Syntax:elink.
  419. :li.:link reftype=hd res=702.Parameters:elink.
  420. :li.:link reftype=hd res=703.Returned results:elink.
  421. :li.:link reftype=hd res=704.Remarks:elink.
  422. :esl.
  423. :h2 res=701 x=30% y=0% height=100% width=70% viewport hide.append_beginlibpath Syntax
  424. :color fc=blue bc=default.
  425. :font facename='System Monospaced' size=22x16.
  426. :p.unsigned long append_beginlibpath&lpar.const char &asterisk. buffer&us.area&rpar.&semi.
  427. :font facename=default size=0x0.
  428. :color fc=default bc=default.
  429. .br
  430. :h3.Example of append_beginlibpath
  431. :xmp.
  432. &numsign.include &odq.lpathext&per.h&cdq.
  433. .br
  434. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  435. &lbrc.
  436. :lm margin=4.
  437. APIRET rc&semi.
  438. HMODULE lib&us.handle&semi.
  439. char buffer&us.area&lbrk.1024&rbrk.&semi.
  440. .br
  441. strcpy&lpar.buffer&us.area, &odq.X&colon.&bsl.&bsl.ThisApp&bsl.&bsl.DLL&cdq.&rpar.&semi.
  442. &slash.&asterisk. Extend further the current LIBPATH extension &asterisk.&slash.
  443. if &lpar.append_beginlibpath&lpar.buffer&us.area&rpar. &xclm.&eq. 0&rpar.
  444. &lbrc.
  445. :lm margin=7.
  446. fputs&lpar.&odq.Unable to extend LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  447. :lm margin=4.
  448. return EXIT&us.FAILURE&semi.
  449. &rbrc.
  450. .br
  451. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  452. rc &eq. DosLoadModule&lpar.buffer&us.area, sizeof buffer&us.area, &odq.DYNALIB&cdq., &.lib&us.handle&rpar.&semi.
  453. &per.
  454. &per.
  455. &per.
  456. :lm margin=1.
  457. .br
  458. &rbrc.
  459. :exmp.
  460. :h2 res=702 x=30% y=0% height=100% width=70% viewport hide.append_beginlibpath Parameters
  461. :p.There is only one parameter for this function&per.
  462. :parml tsize=20 break=all.
  463. :pt.buffer&us.area &lpar.const char &lbrk.&rbrk.&rpar.
  464. :pd.The list of directories to be concatenated onto the end of the current pre&hyphen.system
  465. LIBPATH extension&per.
  466. :eparml.
  467. :h2 res=703 x=30% y=0% height=100% width=70% viewport hide.append_beginlibpath Returned results
  468. :p.This function normally returns zero&per. Any other value indicates an error returned by
  469. the DosSetExtLIBPATH&lpar.&rpar. API&per. The most likely error values to be returned are
  470. 8 &lpar.:hp4.ERROR&us.NOT&us.ENOUGH&us.MEMORY:ehp4.&rpar. and 161
  471. &lpar.:hp4.ERROR&us.BAD&us.PATHNAME:ehp4.&rpar.&per.
  472. :h2 res=704 x=30% y=0% height=100% width=70% viewport hide.append_beginlibpath Remarks
  473. :p.The directory names should be fully qualified and built into a string, separated by
  474. semi&hyphen.colons, just one would when coding the LIBPATH list in CONFIG&per.SYS&per. You
  475. do not need a trailing semi&hyphen.colon&per.
  476. :p.See also the :link reftype=hd res=9.prepend_beginlibpath:elink.&lpar.&rpar. function&per.
  477. :h2 res=8 x=0% y=0% height=100% width=30%.append_endlibpath
  478. :p.This concatenates the supplied list of directories to end of the post&hyphen.system LIBPATH
  479. extension&per.
  480. :link reftype=hd res=801 auto.
  481. :sl.
  482. :li.:link reftype=hd res=801.Syntax:elink.
  483. :li.:link reftype=hd res=802.Parameters:elink.
  484. :li.:link reftype=hd res=803.Returned results:elink.
  485. :li.:link reftype=hd res=804.Remarks:elink.
  486. :esl.
  487. :h2 res=801 x=30% y=0% height=100% width=70% viewport hide.append_endlibpath Syntax
  488. :color fc=blue bc=default.
  489. :font facename='System Monospaced' size=22x16.
  490. :p.unsigned long append_endlibpath&lpar.const char &asterisk. buffer&us.area&rpar.&semi.
  491. :font facename=default size=0x0.
  492. :color fc=default bc=default.
  493. .br
  494. :h3.Example of append_endlibpath
  495. :xmp.
  496. &numsign.include &odq.lpathext&per.h&cdq.
  497. .br
  498. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  499. &lbrc.
  500. :lm margin=4.
  501. APIRET rc&semi.
  502. HMODULE lib&us.handle&semi.
  503. char buffer&us.area&lbrk.1024&rbrk.&semi.
  504. .br
  505. strcpy&lpar.buffer&us.area, &odq.X&colon.&bsl.&bsl.ThisApp&bsl.&bsl.DLL&cdq.&rpar.&semi.
  506. &slash.&asterisk. Extend further the current LIBPATH extension &asterisk.&slash.
  507. if &lpar.append_endlibpath&lpar.buffer&us.area&rpar. &xclm.&eq. 0&rpar.
  508. &lbrc.
  509. :lm margin=7.
  510. fputs&lpar.&odq.Unable to extend LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  511. :lm margin=4.
  512. return EXIT&us.FAILURE&semi.
  513. &rbrc.
  514. .br
  515. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  516. rc &eq. DosLoadModule&lpar.buffer&us.area, sizeof buffer&us.area, &odq.DYNALIB&cdq., &.lib&us.handle&rpar.&semi.
  517. &per.
  518. &per.
  519. &per.
  520. :lm margin=1.
  521. .br
  522. &rbrc.
  523. :exmp.
  524. :h2 res=802 x=30% y=0% height=100% width=70% viewport hide.append_endlibpath Parameters
  525. :p.There is only one parameter for this function&per.
  526. :parml tsize=20 break=all.
  527. :pt.buffer&us.area &lpar.const char &lbrk.&rbrk.&rpar.
  528. :pd.The list of directories to be concatenated onto the end of the current post&hyphen.system
  529. LIBPATH extension&per.
  530. :eparml.
  531. :h2 res=803 x=30% y=0% height=100% width=70% viewport hide.append_endlibpath Returned results
  532. :p.This function normally returns zero&per. Any other value indicates an error returned by
  533. the DosSetExtLIBPATH&lpar.&rpar. API&per. The most likely error values to be returned are
  534. 8 &lpar.:hp4.ERROR&us.NOT&us.ENOUGH&us.MEMORY:ehp4.&rpar. and 161
  535. &lpar.:hp4.ERROR&us.BAD&us.PATHNAME:ehp4.&rpar.&per.
  536. :h2 res=804 x=30% y=0% height=100% width=70% viewport hide.append_endlibpath Remarks
  537. :p.The directory names should be fully qualified and built into a string, separated by
  538. semi&hyphen.colons, just one would when coding the LIBPATH list in CONFIG&per.SYS&per. You
  539. do not need a trailing semi&hyphen.colon&per.
  540. :p.See also the :link reftype=hd res=10.prepend_endlibpath:elink.&lpar.&rpar. function&per.
  541. :h2 res=9 x=0% y=0% height=100% width=30%.prepend_beginlibpath
  542. :p.This concatenates the supplied list of directories to start of the pre&hyphen.system LIBPATH
  543. extension&per.
  544. :link reftype=hd res=901 auto.
  545. :sl.
  546. :li.:link reftype=hd res=901.Syntax:elink.
  547. :li.:link reftype=hd res=902.Parameters:elink.
  548. :li.:link reftype=hd res=903.Returned results:elink.
  549. :li.:link reftype=hd res=904.Remarks:elink.
  550. :esl.
  551. :h2 res=901 x=30% y=0% height=100% width=70% viewport hide.prepend_beginlibpath Syntax
  552. :color fc=blue bc=default.
  553. :font facename='System Monospaced' size=22x16.
  554. :p.unsigned long prepend_beginlibpath&lpar.const char &asterisk. buffer&us.area&rpar.&semi.
  555. :font facename=default size=0x0.
  556. :color fc=default bc=default.
  557. .br
  558. :h3.Example of prepend_beginlibpath
  559. :xmp.
  560. &numsign.include &odq.lpathext&per.h&cdq.
  561. .br
  562. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  563. &lbrc.
  564. :lm margin=4.
  565. APIRET rc&semi.
  566. HMODULE lib&us.handle&semi.
  567. char buffer&us.area&lbrk.1024&rbrk.&semi.
  568. .br
  569. strcpy&lpar.buffer&us.area, &odq.X&colon.&bsl.&bsl.ThisApp&bsl.&bsl.DLL&cdq.&rpar.&semi.
  570. &slash.&asterisk. Extend further the current LIBPATH extension &asterisk.&slash.
  571. if &lpar.prepend_beginlibpath&lpar.buffer&us.area&rpar. &xclm.&eq. 0&rpar.
  572. &lbrc.
  573. :lm margin=7.
  574. fputs&lpar.&odq.Unable to extend LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  575. :lm margin=4.
  576. return EXIT&us.FAILURE&semi.
  577. &rbrc.
  578. .br
  579. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  580. rc &eq. DosLoadModule&lpar.buffer&us.area, sizeof buffer&us.area, &odq.DYNALIB&cdq., &.lib&us.handle&rpar.&semi.
  581. &per.
  582. &per.
  583. &per.
  584. :lm margin=1.
  585. .br
  586. &rbrc.
  587. :exmp.
  588. :h2 res=902 x=30% y=0% height=100% width=70% viewport hide.prepend_beginlibpath Parameters
  589. :p.There is only one parameter for this function&per.
  590. :parml tsize=20 break=all.
  591. :pt.buffer&us.area &lpar.const char &lbrk.&rbrk.&rpar.
  592. :pd.The list of directories to be concatenated onto the start of the current pre&hyphen.system
  593. LIBPATH extension&per.
  594. :eparml.
  595. :h2 res=903 x=30% y=0% height=100% width=70% viewport hide.prepend_beginlibpath Returned results
  596. :p.This function normally returns zero&per. Any other value indicates an error returned by
  597. the DosSetExtLIBPATH&lpar.&rpar. API&per. The most likely error values to be returned are
  598. 8 &lpar.:hp4.ERROR&us.NOT&us.ENOUGH&us.MEMORY:ehp4.&rpar. and 161
  599. &lpar.:hp4.ERROR&us.BAD&us.PATHNAME:ehp4.&rpar.&per.
  600. :h2 res=904 x=30% y=0% height=100% width=70% viewport hide.prepend_beginlibpath Remarks
  601. :p.The directory names should be fully qualified and built into a string, separated by
  602. semi&hyphen.colons, just one would when coding the LIBPATH list in CONFIG&per.SYS&per. You
  603. do not need a trailing semi&hyphen.colon&per.
  604. :p.See also the :link reftype=hd res=7.apppend_beginlibpath:elink.&lpar.&rpar. function&per.
  605. :h2 res=10 x=0% y=0% height=100% width=30%.prepend_endlibpath
  606. :p.This concatenates the supplied list of directories to start of the post&hyphen.system LIBPATH
  607. extension&per.
  608. :link reftype=hd res=1001 auto.
  609. :sl.
  610. :li.:link reftype=hd res=1001.Syntax:elink.
  611. :li.:link reftype=hd res=1002.Parameters:elink.
  612. :li.:link reftype=hd res=1003.Returned results:elink.
  613. :li.:link reftype=hd res=1004.Remarks:elink.
  614. :esl.
  615. :h2 res=1001 x=30% y=0% height=100% width=70% viewport hide.prepend_endlibpath Syntax
  616. :color fc=blue bc=default.
  617. :font facename='System Monospaced' size=22x16.
  618. :p.unsigned long prepend_endlibpath&lpar.const char &asterisk. buffer&us.area&rpar.&semi.
  619. :font facename=default size=0x0.
  620. :color fc=default bc=default.
  621. .br
  622. :h3.Example of prepend_endlibpath
  623. :xmp.
  624. &numsign.include &odq.lpathext&per.h&cdq.
  625. .br
  626. int main&lpar.int argc, char &asterisk.&asterisk. argv&rpar.
  627. &lbrc.
  628. :lm margin=4.
  629. APIRET rc&semi.
  630. HMODULE lib&us.handle&semi.
  631. char buffer&us.area&lbrk.1024&rbrk.&semi.
  632. .br
  633. strcpy&lpar.buffer&us.area, &odq.X&colon.&bsl.&bsl.ThisApp&bsl.&bsl.DLL&cdq.&rpar.&semi.
  634. &slash.&asterisk. Extend further the current LIBPATH extension &asterisk.&slash.
  635. if &lpar.prepend_endlibpath&lpar.buffer&us.area&rpar. &xclm.&eq. 0&rpar.
  636. &lbrc.
  637. :lm margin=7.
  638. fputs&lpar.&odq.Unable to extend LIBPATH extension&per.&cdq., stderr&rpar.&semi.
  639. :lm margin=4.
  640. return EXIT&us.FAILURE&semi.
  641. &rbrc.
  642. .br
  643. :hp9.&slash.&asterisk. Rest of program &asterisk.&slash.:ehp9.
  644. rc &eq. DosLoadModule&lpar.buffer&us.area, sizeof buffer&us.area, &odq.DYNALIB&cdq., &.lib&us.handle&rpar.&semi.
  645. &per.
  646. &per.
  647. &per.
  648. :lm margin=1.
  649. .br
  650. &rbrc.
  651. :exmp.
  652. :h2 res=1002 x=30% y=0% height=100% width=70% viewport hide.prepend_endlibpath Parameters
  653. :p.There is only one parameter for this function&per.
  654. :parml tsize=20 break=all.
  655. :pt.buffer&us.area &lpar.const char &lbrk.&rbrk.&rpar.
  656. :pd.The list of directories to be concatenated onto the start of the current post&hyphen.system
  657. LIBPATH extension&per.
  658. :eparml.
  659. :h2 res=1003 x=30% y=0% height=100% width=70% viewport hide.prepend_endlibpath Returned results
  660. :p.This function normally returns zero&per. Any other value indicates an error returned by
  661. the DosSetExtLIBPATH&lpar.&rpar. API&per. The most likely error values to be returned are
  662. 8 &lpar.:hp4.ERROR&us.NOT&us.ENOUGH&us.MEMORY:ehp4.&rpar. and 161
  663. &lpar.:hp4.ERROR&us.BAD&us.PATHNAME:ehp4.&rpar.&per.
  664. :h2 res=1004 x=30% y=0% height=100% width=70% viewport hide.prepend_endlibpath Remarks
  665. :p.The directory names should be fully qualified and built into a string, separated by
  666. semi&hyphen.colons, just one would when coding the LIBPATH list in CONFIG&per.SYS&per. You
  667. do not need a trailing semi&hyphen.colon&per.
  668. :p.See also the :link reftype=hd res=8.append_endlibpath:elink.&lpar.&rpar. function&per.
  669. :euserdoc.
  670.