Commit 1fcc324ed719e87d5e8f23927ff2549e7a8cbfe6

Authored by Perry Werneck
1 parent d021aee6

Updating docs

src/include/lib3270.h
@@ -1052,23 +1052,23 @@ @@ -1052,23 +1052,23 @@
1052 /** 1052 /**
1053 * @brief Find the buffer address of the field attribute for a given buffer address. 1053 * @brief Find the buffer address of the field attribute for a given buffer address.
1054 * 1054 *
1055 - * @param h Session handle.  
1056 - * @param addr Buffer address of the field. 1055 + * @param hSession Session handle.
  1056 + * @param addr Buffer address of the field.
1057 * 1057 *
1058 - * @return field address or -1 if the screen isn't formatted. 1058 + * @return field address or -1 if the screen isn't formatted (sets errno).
1059 * 1059 *
1060 */ 1060 */
1061 - LIB3270_EXPORT int lib3270_field_addr(H3270 *h, int baddr); 1061 + LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr);
1062 1062
1063 LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr); 1063 LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr);
1064 1064
1065 /** 1065 /**
1066 * @brief Get the length of the field at given buffer address. 1066 * @brief Get the length of the field at given buffer address.
1067 * 1067 *
1068 - * @param h Session handle.  
1069 - * @param addr Buffer address of the field. 1068 + * @param hSession Session handle.
  1069 + * @param addr Buffer address of the field.
1070 * 1070 *
1071 - * @return field length. 1071 + * @return field length or -1 if invalid or not connected (sets errno).
1072 * 1072 *
1073 */ 1073 */
1074 LIB3270_EXPORT int lib3270_field_length(H3270 *h, int baddr); 1074 LIB3270_EXPORT int lib3270_field_length(H3270 *h, int baddr);
src/lib3270/bounds.c
@@ -34,16 +34,22 @@ @@ -34,16 +34,22 @@
34 34
35 /*--[ Implement ]------------------------------------------------------------------------------------*/ 35 /*--[ Implement ]------------------------------------------------------------------------------------*/
36 36
37 -LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *session, int baddr, int *start, int *end) 37 +/**
  38 + * Get field region
  39 + *
  40 + * @param hSession Session handle.
  41 + * @param baddr Reference position to get the field start/stop offsets.
  42 + * @param start return location for start of selection, as a character offset.
  43 + * @param end return location for end of selection, as a character offset.
  44 + *
  45 + * @return -1 if invalid or not connected (sets errno).
  46 + *
  47 + */
  48 +LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *hSession, int baddr, int *start, int *end)
38 { 49 {
39 int first; 50 int first;
40 51
41 - CHECK_SESSION_HANDLE(session);  
42 -  
43 - if(!lib3270_connected(session))  
44 - return -1;  
45 -  
46 - first = lib3270_field_addr(session,baddr); 52 + first = lib3270_field_addr(hSession,baddr);
47 53
48 if(first < 0) 54 if(first < 0)
49 return -1; 55 return -1;
@@ -55,8 +61,8 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *session, int baddr, int *star @@ -55,8 +61,8 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *session, int baddr, int *star
55 61
56 if(end) 62 if(end)
57 { 63 {
58 - int maxlen = (session->rows * session->cols)-1;  
59 - *end = first + lib3270_field_length(session,first); 64 + int maxlen = (hSession->rows * hSession->cols)-1;
  65 + *end = first + lib3270_field_length(hSession,first);
60 if(*end > maxlen) 66 if(*end > maxlen)
61 *end = maxlen; 67 *end = maxlen;
62 } 68 }
src/lib3270/ctlr.c
@@ -483,6 +483,15 @@ LIB3270_EXPORT int lib3270_get_field_len(H3270 *hSession, int baddr) @@ -483,6 +483,15 @@ LIB3270_EXPORT int lib3270_get_field_len(H3270 *hSession, int baddr)
483 return -1; 483 return -1;
484 } 484 }
485 485
  486 +/**
  487 + * @brief Find the buffer address of the field attribute for a given buffer address.
  488 + *
  489 + * @param hSession Session handle.
  490 + * @param addr Buffer address of the field.
  491 + *
  492 + * @return field address or -1 if the screen isn't formatted (sets errno).
  493 + *
  494 + */
486 LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr) 495 LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr)
487 { 496 {
488 int sbaddr; 497 int sbaddr;
@@ -503,6 +512,7 @@ LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr) @@ -503,6 +512,7 @@ LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr)
503 DEC_BA(baddr); 512 DEC_BA(baddr);
504 } while (baddr != sbaddr); 513 } while (baddr != sbaddr);
505 514
  515 + errno = EINVAL;
506 return -1; 516 return -1;
507 } 517 }
508 518
@@ -510,10 +520,13 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr) @@ -510,10 +520,13 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr)
510 { 520 {
511 int sbaddr; 521 int sbaddr;
512 522
513 - CHECK_SESSION_HANDLE(hSession); 523 + FAIL_IF_NOT_ONLINE(hSession);
514 524
515 - if (!hSession->formatted) 525 + if(!hSession->formatted)
  526 + {
  527 + errno = ENOTCONN;
516 return -1; 528 return -1;
  529 + }
517 530
518 sbaddr = baddr; 531 sbaddr = baddr;
519 do 532 do
@@ -523,12 +536,20 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr) @@ -523,12 +536,20 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr)
523 DEC_BA(baddr); 536 DEC_BA(baddr);
524 } while (baddr != sbaddr); 537 } while (baddr != sbaddr);
525 538
  539 + errno = EINVAL;
526 return -1; 540 return -1;
  541 +
527 } 542 }
528 543
529 544
530 -/*  
531 - * Get Field width 545 +/**
  546 + * @brief Get the length of the field at given buffer address.
  547 + *
  548 + * @param hSession Session handle.
  549 + * @param addr Buffer address of the field.
  550 + *
  551 + * @return field length or -1 if invalid or not connected (sets errno).
  552 + *
532 */ 553 */
533 int lib3270_field_length(H3270 *hSession, int baddr) 554 int lib3270_field_length(H3270 *hSession, int baddr)
534 { 555 {
@@ -536,8 +557,6 @@ int lib3270_field_length(H3270 *hSession, int baddr) @@ -536,8 +557,6 @@ int lib3270_field_length(H3270 *hSession, int baddr)
536 int addr; 557 int addr;
537 int width = 0; 558 int width = 0;
538 559
539 - CHECK_SESSION_HANDLE(hSession);  
540 -  
541 addr = find_field_attribute(hSession,baddr); 560 addr = find_field_attribute(hSession,baddr);
542 561
543 if(addr < 0) 562 if(addr < 0)
@@ -553,6 +572,7 @@ int lib3270_field_length(H3270 *hSession, int baddr) @@ -553,6 +572,7 @@ int lib3270_field_length(H3270 *hSession, int baddr)
553 width++; 572 width++;
554 } while (addr != saddr); 573 } while (addr != saddr);
555 574
  575 + errno = EINVAL;
556 return -1; 576 return -1;
557 577
558 } 578 }
@@ -566,11 +586,26 @@ unsigned char get_field_attribute(H3270 *hSession, int baddr) @@ -566,11 +586,26 @@ unsigned char get_field_attribute(H3270 *hSession, int baddr)
566 return hSession->ea_buf[find_field_attribute(hSession,baddr)].fa; 586 return hSession->ea_buf[find_field_attribute(hSession,baddr)].fa;
567 } 587 }
568 588
  589 +/**
  590 + * @brief Find the next unprotected field.
  591 + *
  592 + * @param hSession Session handle.
  593 + * @param baddr0 Search start addr (-1 to use current cursor position).
  594 + *
  595 + * @return address following the unprotected attribute byte, or 0 if no nonzero-width unprotected field can be found, -1 if not connected.
  596 + *
  597 + */
569 LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0) 598 LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0)
570 { 599 {
571 register int baddr, nbaddr; 600 register int baddr, nbaddr;
572 601
573 - CHECK_SESSION_HANDLE(hSession); 602 + FAIL_IF_NOT_ONLINE(hSession);
  603 +
  604 + if(!hSession->formatted)
  605 + {
  606 + errno = ENOTCONN;
  607 + return -1;
  608 + }
574 609
575 if(baddr0 < 0) 610 if(baddr0 < 0)
576 baddr0 = hSession->cursor_addr; 611 baddr0 = hSession->cursor_addr;
@@ -588,13 +623,12 @@ LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0) @@ -588,13 +623,12 @@ LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0)
588 } 623 }
589 624
590 LIB3270_EXPORT int lib3270_get_is_protected_at(H3270 *h, int row, int col) { 625 LIB3270_EXPORT int lib3270_get_is_protected_at(H3270 *h, int row, int col) {
591 - CHECK_SESSION_HANDLE(h);  
592 return lib3270_get_is_protected(h, ((row-1) * h->cols) + (col-1)); 626 return lib3270_get_is_protected(h, ((row-1) * h->cols) + (col-1));
593 } 627 }
594 628
595 LIB3270_EXPORT int lib3270_get_is_protected(H3270 *hSession, int baddr) 629 LIB3270_EXPORT int lib3270_get_is_protected(H3270 *hSession, int baddr)
596 { 630 {
597 - CHECK_SESSION_HANDLE(hSession); 631 + FAIL_IF_NOT_ONLINE(hSession);
598 632
599 if(baddr < 0) 633 if(baddr < 0)
600 baddr = hSession->cursor_addr; 634 baddr = hSession->cursor_addr;
@@ -1163,10 +1197,8 @@ void ctlr_erase_all_unprotected(H3270 *hSession) @@ -1163,10 +1197,8 @@ void ctlr_erase_all_unprotected(H3270 *hSession)
1163 ALL_CHANGED(hSession); 1197 ALL_CHANGED(hSession);
1164 } 1198 }
1165 1199
1166 -  
1167 -  
1168 -/*  
1169 - * Process a 3270 Write command. 1200 +/**
  1201 + * @brief Process a 3270 Write command.
1170 */ 1202 */
1171 enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean erase) 1203 enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean erase)
1172 { 1204 {
@@ -1993,9 +2025,8 @@ enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean er @@ -1993,9 +2025,8 @@ enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean er
1993 #undef ABORT_WRITEx 2025 #undef ABORT_WRITEx
1994 #undef ABORT_WRITE 2026 #undef ABORT_WRITE
1995 2027
1996 -/*  
1997 - * Write SSCP-LU data, which is quite a bit dumber than regular 3270  
1998 - * output. 2028 +/**
  2029 + * @brief Write SSCP-LU data, which is quite a bit dumber than regular 3270 output.
1999 */ 2030 */
2000 void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen) 2031 void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen)
2001 { 2032 {
@@ -2095,7 +2126,9 @@ void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen) @@ -2095,7 +2126,9 @@ void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen)
2095 2126
2096 #if defined(X3270_DBCS) /*[*/ 2127 #if defined(X3270_DBCS) /*[*/
2097 2128
2098 -/* 2129 +/**
  2130 + * @brief Determine the DBCS state of a buffer location strictly by looking left.
  2131 + *
2099 * Determine the DBCS state of a buffer location strictly by looking left. 2132 * Determine the DBCS state of a buffer location strictly by looking left.
2100 * Used only to validate write operations. 2133 * Used only to validate write operations.
2101 * Returns only DBCS_LEFT, DBCS_RIGHT or DBCS_NONE. 2134 * Returns only DBCS_LEFT, DBCS_RIGHT or DBCS_NONE.
@@ -2367,7 +2400,7 @@ int ctlr_dbcs_postprocess(H3270 *hSession) @@ -2367,7 +2400,7 @@ int ctlr_dbcs_postprocess(H3270 *hSession)
2367 #endif /*]*/ 2400 #endif /*]*/
2368 2401
2369 /** 2402 /**
2370 - * Process pending input. 2403 + * @brief Process pending input.
2371 * 2404 *
2372 * @param hSession Session handle. 2405 * @param hSession Session handle.
2373 */ 2406 */
@@ -2464,10 +2497,8 @@ static void ctlr_blanks(H3270 *session) @@ -2464,10 +2497,8 @@ static void ctlr_blanks(H3270 *session)
2464 ALL_CHANGED(session); 2497 ALL_CHANGED(session);
2465 } 2498 }
2466 2499
2467 -  
2468 /** 2500 /**
2469 - * Change a character in the 3270 buffer, removes any field attribute defined at that location.  
2470 - * 2501 + * @brief Change a character in the 3270 buffer, removes any field attribute defined at that location.
2471 * 2502 *
2472 */ 2503 */
2473 void ctlr_add(H3270 *hSession, int baddr, unsigned char c, unsigned char cs) 2504 void ctlr_add(H3270 *hSession, int baddr, unsigned char c, unsigned char cs)
src/lib3270/testprogram/testprogram.c
@@ -11,7 +11,7 @@ int main(int numpar, char *param[]) @@ -11,7 +11,7 @@ int main(int numpar, char *param[])
11 { 11 {
12 H3270 * h; 12 H3270 * h;
13 int rc = 0; 13 int rc = 0;
14 - const char * url = getenv("TN3270URL"); 14 + const char * url = getenv("LIB3270_DEFAULT_HOST");
15 15
16 16
17 h = lib3270_session_new(""); 17 h = lib3270_session_new("");